2. EPMO Open Source Coordination Office Redaction File Detail Report

Produced by Araxis Merge on 3/27/2017 3:36:32 PM Central Daylight Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.

2.1 Files compared

#	Location	File	Last Modified
1	XU_80_680T1.zip	krn8_0dg.docx	Mon Mar 27 20:09:12 2017 UTC
2	XU_80_680T1.zip	krn8_0dg.docx	Mon Mar 27 20:19:39 2017 UTC

2.2 Comparison summary

Description	Between Files 1 and 2
Description	Text Blocks	Lines
Unchanged	35	43438
Changed	29	66
Inserted	0	0
Removed	5	5

2.3 Comparison options

Whitespace
Character case	Differences in character case are significant
Line endings	Differences in line endings (`CR` and `LF` characters) are ignored
CR/LF characters	Not shown in the comparison detail

2.4 Active regular expressions

No regular expressions were active.

2.5 Comparison detail

	1	Kernel 8.0 & Kernel Toolkit 7. 3
	2	Developer’ s Guide
	3
	4	December 2 016
	5
	6	Department of Vetera ns Affairs (VA)
	7	Office of Informatio n and Tech nology (OI &T)
	8	Enterprise Program M anagement Office (EP MO)
	9
	10
	11	Revision H istory
	12
	13	Date
	14	Revision
	15	Descriptio n
	16	Author
	17	11/17/2016
	18	11.9
	19	Tech Edits for XU8. 0680
	20	Added Sect ion 31.11 JSON Conve rsion Func tions.
	21	Developer: B. I.
	22	08/10/2016
	23	11.8
	24	Tech Edits :
	25	Updated VA Directive reference in the “S oftware Di sclaimer” section.
	26	Added VPID caution n ote to Sec tions 4.1. 1 and 4.1. 2.
	27	Updated “S ecurity ID (SECID)” in Section 4.1.3.
	28	Added “IPv 6-ready” n ote to Sec tions 6.2. 16, 6.2.17 , 7.1.1, a nd 7.1.2.
	29	Updated th e IPADDRES S variable descripti on in Sect ion 6.2.16 .
	30	Added an I Pv6 exampl e to Secti on 7.1.2.
	31	Added refe rence to K ernel Tool kit patch XT7.3138 in Sectio ns 27.4.1, 27.4.3, 2 7.4.5, and 27.4.6.
	32	Added the .xt8meth i nput param eter and r eference l inks to Se ction 27.4 .3.
	33	Added refe rence to K ernel Tool kit patch XT7.3138 in Sectio n 27.7.1.
	34	Developers : H. W.
	35	Technical Writer: T. B.
	36	07/19/2016
	37	11.7
	38	Tech Edits :
	39	Updated th e “XML Par ser (VistA ): Develop er Tools” section. A dded overv iew conten t from the standalon e VistA XM L Parser T echnical a nd User Do cumentatio n (Patches XT7.358 & 67).
	40	Updated th e $$PATCH^ XPDUTL(): Verify Pat ch Install ation API to correct the examp le based o n NSD Inci dent I6524 269FY16.
	41	Replaced “ Integratio n Agreemen t (IA)” wi th “Integr ation Cont rol Regist ration (IC R)” throug hout the d ocument.
	42	Updated th e $$CREATE ^XUSAP: Cr eate Appli cation Pro xy User AP I based on feedback from H. W.
	43	Added the “Developin g a File M erge Capab ility” sec tion (cont ent taken from Kerne l Toolkit 7.3 User M anual).
	44	Added Caut ion note r egarding m odificatio n of Kerne l routines in the “S oftware Di sclaimer” section.
	45	Removed al l API tabl es used to format AP I data for Section 5 08 conform ance.
	46	Developers : R. D.; H . W.
	47	Technical Writer: T. B.
	48	10/20/2015
	49	11.6
	50	Tech Edits :
	51	Updated th e followin g APIs:
	52	$$GETURL^X THC10: Ret urn URL Da ta Using H TTP API.
	53	$$MAKEURL^ XTHCURL: C reates a U RL from Co mponents A PI.
	54	$$ENCODE^X THCURL: En codes a Qu ery String API.
	55	$$PARSEURL ^XTHCURL: Parses a U RL API.
	56	$$DECODE^X THCUTL: De codes a St ring API.
	57	Corrected Example 2 in the SAY ^XGF(): Sc reen Strin g API.
	58	Added the “^XTMP Glo bal: Devel oper Tools ” section.
	59	Updated Ta ble 14 in Section 15 .2.4.5.
	60	Added “Dat a Security : Develope r Tools” s ection and APIs base d on Kerne l patch XU 8.0655. The follow ing APIS w ere added:
	61	$$AESDECR^ XUSHSH(): Returns Pl aintext St ring Value for AES E ncrypted C iphertext Entry API.
	62	$$AESENCR^ XUSHSH(): Returns AE S Encrypte d Cipherte xt for Str ing Entry API.
	63	$$B64DECD ^XUSHSH(): Returns D ecoded Val ue for a B ase64 Stri ng Entry A PI.
	64	$$B64ENCD^ XUSHSH(): Returns Ba se64 Encod ed Value f or a Strin g Entry AP I.
	65	$$RSADECR^ XUSHSH(): Returns Pl aintext St ring Value for RSA E ncrypted C iphertext Entry API.
	66	$$RSAENCR^ XUSHSH(): Returns RS A Encrypte d Cipherte xt for Str ing Entry API.
	67	$$SHAHASH^ XUSHSH(): Returns SH A Hash for a String Entry API.
	68	Developers : H. W.
	69	Technical Writer: T. B.
	70	06/11/2015
	71	11.5
	72	Updated th e followin g:
	73	Merged (an d then del eted) the “Toolkit—V istA XML P arser APIs ” section into the “ XML Parser (VistA): Developer Tools” sec tion, sinc e they had duplicate API conte nt.
	74	Updated do cument for Kernel To olkit patc h XT7.38 1. Added t he “Toolki t—M Unit” section (H . W.).
	75	Updated do cument for Kernel Pa tches XU8 .0605 and 638. Adde d the foll owing APIs to the “A pplication Programmi ng Interfa ce (API)” section in the “XLF Function L ibrary: De veloper To ols” secti on (H. W.) :
	76	Added the “$$CONVERT ^XLFIPV(): " API.
	77	Added the “$$FORCEIP 4^XLFIPV() : Convert any IP Add ress to IP v4" API.
	78	Added the “$$FORCEIP 6^XLFIPV() : Convert any IP Add ress to IP v6" API.
	79	Added the “$$VALIDAT E^XLFIPV() : Validate IP Addres s Format" API.
	80	Added the “$$VERSION ^XLFIPV: S how System Settings for IPv6" API.
	81	Updated th e $$SCH^XL FDT(): Nex t Schedule d Runtime API: Added Example 4 (M. A. F. ).
	82	Updated th e “$$ADDRE SS^XLFNSLK (): Conver t Domain N ame to IP Addresses” API for c hanges to IPv4 and I Pv6 in Ker nel patch XU8.0638 .
	83	Merged the DELSTAT^X QALBUTL AP I content with the D ELSTAT^XQA LBUTL(): A PI.
	84	Added the following APIs in th is manual to the onl ine HTML A PIs:
	85	Toolkit—Du plicate Re cord Merge
	86	Toolkit—KE RMIT APIs
	87	Toolkit—Mu lti-Term L ook-Up (MT LU) APIs
	88	Toolkit—M Unit Utili ty
	89	Toolkit—Pa rameter To ols
	90	Reformatte d document to follow latest do cumentatio n standard s and form atting rul es. Also, formatted document f or online presentati on vs. pri nt present ation (i.e ., for dou ble-sided printing). These cha nges inclu de:
	91	Revised se ction page setup.
	92	Removed se ction head ers.
	93	Revised do cument foo ters.
	94	Removed bl ank pages between se ctions.
	95	Revised al l heading style form atting.
	96	Developers : M. A. F. , H. W.
	97	Technical Writer: T. B.
	98	09/24/2014
	99	11.4
	100	Updated th e followin g:
	101	$$LOOKUP^X USER(): Ne w Person F ile Lookup API: mino r correcti ons and us ed example in this g uide to ma tch and sc rub exampl es in onli ne API.
	102	$$NAME^XUS ER(): Get Name of Us er API: fi xed index entries.
	103	“$$DEA^XUS ER()—Get U ser’s DEA Number" AP I: Added i en input p arameter a nd Example 4.
	104	Added stat ement to S ection 15. 2.4.4 as p er Remedy Ticket #63 050.
	105	Changed al l referenc es from “O IT” to “OI &T” throug hout.
	106	Developer: R. M.
	107	Technical Writer: T. B.
	108	04/07/2014
	109	11.3
	110	Added a pa tch refere nce note a nd made mi nor edits/ updates to the follo wing APIs:
	111	^%ZIS: Sta ndard Devi ce Call AP I.
	112	REQ^%ZTLOA D: Requeue a Task AP I.
	113	SETCLEAN^X ULMU(): Re gister a C leanup Rou tine API.
	114	UNCLEAN^XU LMU(): Rem ove Entrie s from the Houseclea ning Stack API.
	115	CLEANUP^XU LMU(): Exe cute the H ousecleani ng Stack A PI.
	116	PAT^XULMU( ): Get a S tandard Se t of Patie nt Identif iers API.
	117	ADDPAT^XUL MU(): Add Patient Id entifiers for a Comp utable Fil e Referenc e API.
	118	Updated th e ^%ZOSF() : Operatin g System-d ependent L ogic Globa l API. Cha nged refer ence in (“ LOAD”) fro m “DIE” to “DIF”, pe r C. G.
	119	Added patc h release reference note to $$ GET^XUA4A7 2(): Get S pecialty a nd Subspec ialty for a User and $$IEN2COD E^XUA4A72( ): Get VA Code APIs.
	120	Redacted d ocument fo r the foll owing info rmation:
	121	Names (rep laced with role and initials).
	122	Production IP addres ses and po rts.
	123	VA Intrane t websites .
	124	Developer: C. G.
	125	Technical Writer: T. B.
	126	05/31/2013
	127	11.2
	128	Updates:
	129	Updated do cument for Word acce ssibility issues for Section 5 08 conform ance.
	130	Made gener al style a nd format updates as needed.
	131	Added the following APIs relea sed with K ernel Lock Manager ( Patch XU8 .0608) in the new “ Lock Manag er: Develo per Tools” section:
	132	SETCLEAN^X ULMU(): Re gister a C leanup Rou tine API.
	133	UNCLEAN^XU LMU(): Rem ove Entrie s from the Houseclea ning Stack API.
	134	CLEANUP^XU LMU(): Exe cute the H ousecleani ng Stack A PI.
	135	PAT^XULMU( ): Get a S tandard Se t of Patie nt Identif iers API.
	136	ADDPAT^XUL MU(): Add Patient Id entifiers for a Comp utable Fil e Referenc e API.
	137	Updated/Co rrected al l URLs (ac tive and i nactive)
	138	Updated do cument for Section 5 08 conform ance;
	139	Added book marks (ide ntifiers) to all tab les.
	140	Changed al l floating callout b oxes to in -line boxe s.
	141	Added scre en tips to all activ e URLs.
	142	Developer: A. C.
	143	Technical Writer: T. B.
	144	04/30/2013
	145	11.1
	146	Updates:
	147	Updated do cument for Kernel pa tch XU8.0 580. Adde d the foll owing APIs to the “A pplication Programmi ng Interfa ce (API)” section in the “User : Develope r Tools” s ection:
	148	Updated th e “$$DEA^X USER()—Get User’s DE A Number” API.
	149	Added the “$$DETOX^X USER()—Get Detox/Mai ntenance I D Number" API.
	150	Added the “$$SDEA^XU SER()—Chec k for Pres cribing Pr ivileges" API.
	151	Added the “$$VDEA^XU SER()—Chec k if User Can Sign C ontrolled Substance Orders" AP I.
	152	Reformatte d document to follow current s tyle guide s and stan dards.
	153	Replaced r eferences from “VA F ileMan Get ting Start ed Manual” to “VA Fi leMan User Manual,” since the next VA Fi leMan 22.n software version wi ll create a new “VA FileMan Ge tting Star ted Manual .”
	154	Updated th e ZTCPU in put variab le descrip tion in th e ^%ZTLOAD : Queue a Task API, as per ema il feedbac k on 10/04 /12 from J . Garcia.
	155	HD00000007 48766: Upd ated the f ollowing A PIs;
	156	$$ID^XUAF4 (): Instit ution Iden tifier
	157	$$IDX^XUAF 4(): Insti tution IEN (Using Co ding Syste m & ID)
	158	$$IEN^XUMF (): Instit ution IEN (Using IFN , Coding S ystem, & I D)
	159	HD00000005 98920: Add ed documen tation for the XPD N O_EPP_DELE TE paramet er to the new “Key P arameters during Pre - and Post -Install R outines” s ection, as requested by A. Las hley.
	160	HD00000003 89572: Rem oved the o bsolete Se ction 11.2 , “Link to the OBJEC T File”, a s per emai l discussi on between G. B. and M. T. on 03/23/2010 ; see Reme dy Ticket #HD0000000 389572.
	161	Patch XU8 .0546: Re moved Supp ort for De vice Hunt Groups. Th is include s removal of the *HU NT GROUP ( #29) and H UNT GROUP DEVICE (#3 0) fields in the DEV ICE file ( #3.5). Sit es had to remove any HUNT GROU P devices before ins talling th is patch u sing VA Fi leMan to f ind any ex isting Hun t Groups. Removed an y referenc es to “Hun t Groups” from this document.
	162	Added the following XPDPROT AP Is release d with Ker nel patch XU8.0547 :
	163	$$ADD^XPDP ROT(): Add Child Pro tocol to P arent Prot ocol.
	164	$$DELETE^X PDPROT(): Delete Chi ld Protoco l from Par ent Protoc ol.
	165	FIND^XPDPR OT(): Find All Paren ts for a P rotocol.
	166	$$LKPROT^X PDPROT(): Look Up Pr otocol IEN .
	167	OUT^XPDPRO T(): Edit Protocol’s Out of Or der Messag e.
	168	RENAME^XPD PROT(): Re name Proto col.
	169	$$TYPE^XPD PROT(): Ge t Protocol Type.
	170	Added blue font high lighting a nd underli ne to sign ify intern al links t o figures, tables, o r sections for ease of use, si milar to w hat one se es to hype rlinks on a Web page .
	171	Updated do cument for Section 5 08 conform ance using word’s bu ilt-in Acc essibility check:
	172	Added tabl e bookmark s.
	173	Added scre en tips fo r all URL links.
	174	Changed al l floating callout b oxes to in -line, cau sing refor matting of numerous dialogue s creen capt ures.
	175	Developers : G. B., J . G., J. I ., A. L. J . M., R. M en., R. Me t., and M. T.
	176	Technical Writer: T. B.
	177	07/26/2012
	178	11.0
	179	Updates:
	180	$$SETUP1^X QALERT: Se nd Alerts. Corrected the descr iptions fo r the XQAA RCH and XQ ASUPV vari ables base d on feedb ack from J . I.
	181	Updated th e “OPEN^%Z ISUTL(): O pen Device with Hand le" API. C orrected r eference t o the CLOS E^%ZISUTL( ): Close D evice with Handle AP I, based o n feedback from H. W .
	182	Added the “XU USER S TART-UP Op tion” sect ion. The X U USER STA RT-UP opti on was add ed with Ke rnel patch XU8.059 3.
	183	Reordered sections i n Section 26, “Toolk it: Develo per Tools, ” to discu ss all API s before g eneral Too lkit devel oper tools /options.
	184	Added/Prom oted the “ XINDEX” se ction base d on the f ollowing:
	185	Open Sourc e Electron ic Health Record Age nt (OSEHRA ) software quality c ertificati on dashboa rd review of VistA F reedom of Informatio n Act (FOI A) code us ing the XI NDEX tool by G. W. a nd R. A.
	186	Code revie w and upda tes by R. D. related to Kernel Toolkit p atch XT7. 3132.
	187	Created a new VA Int ranet Kern el Toolkit XINDEX we bsite.
	188	Updated th e “%Index of Routine s Option—X INDEX" bas ed on addi tion of ne w XINDEX s ection and feedback from devel oper relat ed to Kern el Toolkit patch XT* 7.3*132.
	189	Added the TOUCH^XUSC LEAN: Noti fy Kernel of Tasks t hat Run 7 Days or Lo nger API t o this doc ument afte r already being adde d to VA In tranet onl ine Kernel APIs; bas ed on emai l from G. B. dated 0 2/08/11.
	190	Revised al l version numbers in the “Revi sion Histo ry” sectio n.
	191	Updated th e “Orienta tion” sect ion.
	192	Updated th e overall document f or current national documentat ion standa rds and st yle guides . For exam ple:
	193	Changed al l Heading n styles t o use Aria l font.
	194	Changed al l Heading n styles t o be left justified.
	195	Software V ersions:
	196	Kernel 8.0
	197	Toolkit 7. 3
	198	Office of Informatio n Field Of fice (OIFO ):
	199	Maintenanc e Project Manager: J . Sch
	200	Developers : R. A., G . B., R. D ., J. I., H. W., and G. W.
	201	Technical Writer: T. B.
	202	10/18/2011
	203	10.1
	204	Updates:
	205	Updated th e “STDNAME ^XLFNAME() : Name Sta ndardizati on Routine " API for Kernel pat ch XU8.0 535.
	206	Updated fo rmatting a nd interna l styles.
	207	Software V ersions:
	208	Kernel 8.0
	209	Toolkit 7. 3
	210	Office of Informatio n Field Of fice (OIFO ):
	211	Maintenanc e Project Manager: J . Sch.
	212	Developer: R. Men.
	213	Technical Writer: T. B.
	214	09/15/2011
	215	10.0
	216	Updates:
	217	Made opt p arameter o ptional in the$$EN^M XMLDOM(): XML—Initia l Processi ng, Build In-memory Image API.
	218	Added Caut ionary Not e to the $ $CREATE^XU SAP: Creat e Applicat ion Proxy User API.
	219	Updated th e $$SCH^XL FDT(): Nex t Schedule d Runtime API exampl es, as per suggestio n by devel oper via e mail.
	220	Updated th e $$SCREEN ^XTID(): G et Screeni ng Conditi on (Term/C oncept) AP I based on Remedy #H D000000039 1324.
	221	Made other minor for mat, style , grammar, and punct uation upd ates.
	222	Updated ^% ZTER: Kern el Standar d Error Re cording Ro utine API to remove statement about NEWi ng all var iables. Th is does no t apply fo r this API .
	223	Changed al l referenc e to NEWin g variable s from “NE W all vari ables.” to “NEW all non-namesp aced varia bles” and removed fo llow-up ex planation throughout the docum ent.
	224	Updated $$ DELETE^XPD MENU(): De lete Menu Item API. Corrected documentat ion to sho w this as an extrins ic functio n.
	225	Updated $$ LKOPT^XPDM ENU(): Loo k Up Optio n IEN API. Corrected documenta tion to sh ow this as an extrin sic functi on.
	226	Added the new $$TYPE ^XPDMENU() : Get Opti on Type AP I.
	227	Added Sect ion 26.5, “Toolkit—H TTP Client APIs.” an d the foll owing APIs :
	228	$$GETURL^X THC10: Ret urn URL Da ta Using H TTP.
	229	$$ENCODE^X THCURL: En codes a Qu ery String .
	230	$$MAKEURL^ XTHCURL: C reates a U RL from Co mponents.
	231	$$PARSEURL ^XTHCURL: Parses a U RL.
	232	$$DECODE^X THCUTL: De codes a St ring.
	233	Updates Se ction 14.2 .4.3.2, “S ending Sec urity Code s” to incl ude refere nce to VA FileMan FI LESEC^DDMO D to set s ecurity ac cess.
	234	Updated/Cl arified Se ction 14.2 .4.3.5, “P artial DD (Some Fiel ds),” and added Figu re 54. KID S—Partial DD: Choosi ng DD leve ls (top le vel and Mu ltiple) to send.
	235	Added NOTE regarding Class 3 a nd FORCED queuing re lated to K ernel Patc hes XU8.0 546/556 t o the top of Section 5, “Devic e Handler: Developer Tools.”
	236	Updated th e “$$LAST^ XPDUTL(): Last Softw are Patch" API based on Kernel patch XU* 8.0*559.
	237	Added the XPDNM(“TST ”) and XPD NM(“SEQ”) variables to Table 9 . KIDS—Key variables during th e environm ent check and Table 14. KIDS—K ey variabl es during the pre- a nd post-in stall rout ines, as p er Kernel patch XU8 .0559.
	238	Software V ersions:
	239	Kernel 8.0
	240	Toolkit 7. 3
	241	Office of Informatio n Field Of fice (OIFO ):
	242	Maintenanc e Project Manager: J . Sch.
	243	Developer: G. B. & R . D.
	244	Technical Writer: T. B.
	245	03/18/2010
	246	9.0
	247	Added the text “Any routine th at is spec ified is a utomatical ly sent by KIDS. You do not ha ve to list the routi ne in the Build Comp onents sec tion.” to the follow ing sectio ns:
	248	14.3.1, “E nvironment Check Rou tine.”
	249	14.3.3, “P re- and Po st-Install Routines: Special F eatures.”
	250	Software V ersions:
	251	Kernel 8.0
	252	Toolkit 7. 3
	253	OIFO:
	254	Maintenanc e Project Manager: J . Sch.
	255	Developer: R. D.
	256	Technical Writer: T. B.
	257	11/16/2009
	258	8.0
	259	Updates:
	260	Added the SUROFOR^XQ ALSURO(): Return a S urrogate’s List of U sers API.
	261	Deleted SU ROLIST^XQA LSUR1 API and added the SUROLI ST^XQALSUR O(): List Surrogates for a Use r API.
	262	Updated AP Is to chan ge input p arameter t o Input Va riable for EN^XQH: D isplay Hel p Frames a nd EN1^XQH : Display Help Frame s APIs.
	263	Updated in put variab le for ^%Z TER: Kerne l Standard Error Rec ording Rou tine API.
	264	Updated WI TNESS^XUVE RIFY(): Re turn IEN o f Users wi th A/V Cod es & Secur ity Keys A PI.
	265	Updated Se ction 17, “Miscellan eous: Deve loper Tool s.” Added the follow ing sectio ns from th e Kernel S ystems Man agement Gu ide to the Kernel De veloper’s Guide, bec ause the f unctions d ocumented are more d eveloper-r elated tha n system m anagement- related:
	266	Programmer Options M enu
	267	^%Z Editor
	268	Updated Se ction 26, “Toolkit: Developer Tools.” Ad ded the fo llowing se ctions fro m the Kern el Systems Managemen t Guide to the Kerne l Develope r’s Guide, because t he functio ns documen ted are mo re develop er-related than syst em managem ent-relate d:
	269	Toolkit—Ro utine Tool s
	270	Toolkit—Ve rification Tools
	271	Updated th e introduc tory conte nt in Sect ion 29, “X GF Functio n Library: Developer Tools.” M oved the X GF Functio n Library content fr om the Ker nel System s Manageme nt Guide t o the Kern el Develop er’s Guide , because the functi ons docume nted are m ore develo per-relate d than sys tem manage ment-relat ed.
	272	Reviewed a nd updated all secti ons for mi nor format changes ( e.g., bull eted lists and table s), style updates, s pelling, a nd grammar fixes.
	273	Added GSEL node to ^ %ZOSF(): O perating S ystem-depe ndent Logi c Global A PI.
	274	Software V ersions:
	275	Kernel 8.0
	276	Toolkit 7. 3
	277	OIFO:
	278	Maintenanc e Project Manager: J . Sch.
	279	Developers : J. I. an d W. F.
	280	Technical Writer: T. B.
	281	07/09/2009
	282	7.4
	283	Updates:
	284	After deve loper re-r eview, cor rected ref erence typ e from “Co ntrolled S ubscriptio n” back to “Supporte d” for the $$OS^%ZOS V: Get Ope rating Sys tem Inform ation API and update d the ICR # to 10097 . Updated the FORUM ICR.
	285	Added ICR # 10097 to the $$VER SION^%ZOSV (): Get OS Version N umber or N ame API.
	286	Software V ersions:
	287	Kernel 8.0
	288	Toolkit 7. 3
	289	OIFO:
	290	Maintenanc e Project Manager: J . Sch.
	291	Developer: G. B.
	292	Technical Writer: T. B.
	293	07/02/2009
	294	7.3
	295	Updates:
	296	Corrected reference type from “Supported ” to Contr olled Subs cription” for the $$ OS^%ZOSV: Get Operat ing System Informati on API.
	297	Software V ersions:
	298	Kernel 8.0
	299	Toolkit 7. 3
	300	OIFO:
	301	Maintenanc e Project Manager: J . Sch.
	302	Developer: G. B.
	303	Technical Writer: T. B.
	304	06/23/2009
	305	7.2
	306	Updates:
	307	Added new section, “ Long Runni ng Tasks—U sing ^%ZIS " to Secti on 25.
	308	Renamed “W riting Two -step Task s” section to “Long Running Ta sks—Writin g Two-step Tasks" in Section 2 5.
	309	Reformatte d document to add ou tline numb ering.
	310	Software V ersions:
	311	Kernel 8.0
	312	Toolkit 7. 3
	313	OIFO:
	314	Maintenanc e Project Manager: J . Sch.
	315	Developer: G. B.
	316	Technical Writer: T. B.
	317	05/04/2009
	318	7.1
	319	Updates:
	320	Patch XT7 .3111, re leased FEB 13, 2009. Included new sectio n titled “ Toolkit—Da ta Standar dization A PIs" in th e Toolkit: Developer Tools sec tion.
	321	Background : Toolkit— Developed Data Stand ardization APIs to s upport Dat a Standard ization’s effort to allow the mapping of one term to another term.
	322	Software V ersions:
	323	Kernel 8.0
	324	Toolkit 7. 3
	325	OIFO:
	326	Maintenanc e Project Manager: J . Sch.
	327	Developer: G. B.
	328	Technical Writer: T. B.
	329	04/27/2009
	330	7.0
	331	Updates:
	332	Updated $$ SCREEN^XTI D(): Get S creening C ondition ( Term/Conce pt) API (I CR # 4631) for Kerne l Toolkit patch XT7 .3108.
	333	Updated ^X UWORKDY: W orkday Cal culation ( Obsolete) API.
	334	Added $$EN ^XUWORKDY: Number of Workdays Calculatio n API.
	335	Added $$WO RKDAY^XUWO RKDY: Work day Valida tion API.
	336	Added $$WO RKPLUS^XUW ORKDY: Wor kday Offse t Calculat ion API.
	337	Updated $$ PATCH^XPDU TL(): Veri fy Patch I nstallatio n.
	338	Updated th e “Orienta tion” sect ion.
	339	Updated or ganization al referen ces.
	340	Minor form at updates (e.g., re ordered th e document Revision History ta ble to dis play lates t to earli est).
	341	Other mino r format u pdates to correspond with the latest sta ndards and style gui des.
	342	Software V ersions:
	343	Kernel 8.0
	344	Toolkit 7. 3
	345	OIFO:
	346	Maintenanc e Project Manager: J . Sch.
	347	Developers : G. B., A . C., W. F ., J. G., J. I., R. Men., R. M et., S. O. , and B. T .
	348	Technical Writer: T. B.
	349	10/28/2008
	350	6.3
	351	Updates:
	352	Table 26: Added “DEV ” entity a nd correct ed the OE/ RR LIST fi le number from “101. 21” to the correct “ 100.21” fi le number.
	353	Updated re ferences t o the CHCK SUM^XTSUMB LD direct mode utili ty and add ed referen ces to CHE CK^XTSUMBL D and CHEC K1^XTSUMBL D routines in Table 28 in Sect ion 26, “T oolkit: De veloper To ols.”
	354	Minor form at updates .
	355	Software V ersions:
	356	Kernel 8.0
	357	Toolkit 7. 3
	358	OIFO:
	359	Maintenanc e Project Manager: J . Sch.
	360	Developers : G. B., A . C., W. F ., J. G., J. I., R. Men., R. M et., S. O. , and B. T .
	361	Technical Writer: T. B.
	362	10/01/2008
	363	6.2
	364	Updates:
	365	Minor form at updates (e.g., re ordered do cument Rev ision Hist ory table to display latest to earliest) .
	366	DE^XUSHSHP : Decrypt Data Strin g API.
	367	EN^XUSHSHP : Encrypt Data Strin g API.
	368	HASH^XUSHS HP: Hash E lectronic Signature Code.
	369	Software V ersions:
	370	Kernel 8.0
	371	Toolkit 7. 3
	372	OIFO:
	373	Maintenanc e Project Manager: J . Sch.
	374	Developers : G. B., A . C., W. F ., J. G., J. I., R. Men., R. M et., S. O. , and B. T .
	375	Technical Writer: T. B.
	376	08/07/2008
	377	6.1
	378	Updates:
	379	Made gener al formatt ing and or ganization al referen ce changes where app ropriate.
	380	Changed re ferences f rom “%INDE X” to “XIN DEX” where appropria te.
	381	Updated Ta ble 8, las t two entr ies.
	382	Updated “P RE-TRANSPO RTATION RO UTINE fiel d (#900)” section to show use of the XPD GREF varia ble in Pre -install, Environmen t Check, a nd/or Post -install r outines.
	383	Removed Ap pendix A—K IDS Build Checklists (Obsolete ).
	384	API Update s:
	385	$$MV^%ZISH (): Rename Host File .
	386	$$NODEV^XU TMDEVQ(): Force Queu ing—No Dev ice Select ion—Update d input pa rameters.
	387	$$INSTALDT ^XPDUTL(): Return Al l Install Dates/Time s.
	388	UPDATE^XPD ID(): Upda te Install Progress Bar.
	389	Moved INIT ^XPDID: Pr ogress Bar Emulator: Initializ e Device a nd Draw Bo x Borders API to “Mi scellaneou s: Develop er Tools” section.
	390	Moved TITL E^XPDID(): Progress Bar Emulat or: Displa y Title Te xt API to “Miscellan eous: Deve loper Tool s” section .
	391	Moved EXIT ^XPDID(): Progress B ar Emulato r: Restore Screen, C lean Up Va riables, a nd Display Text API to “Miscel laneous: D eveloper T ools” sect ion.
	392	OP^XQCHK() : Current Option Che ck.
	393	ENDR^%ZISS : Set Up S pecific Sc reen Handl ing Variab les.
	394	$$ASKSTOP^ %ZTLOAD: S top TaskMa n Task.
	395	Software V ersions:
	396	Kernel 8.0
	397	Toolkit 7. 3
	398	OIFO:
	399	Maintenanc e Project Manager: J . Sch.
	400	Developers : G. B., A . C., W. F ., J. G., J. I., R. Men., R. M et., S. O. , and B. T .
	401	Technical Writer: T. B.
	402	01/07/2008
	403	6.0
	404	I Updates:
	405	$$CJ^XLFST R(): Cente r Justify String.
	406	$$LJ^XLFST R(): Left Justify St ring.
	407	$$RJ^XLFST R(): Right Justify S tring.
	408	DELETE^XQA LERT: Clea r Obsolete Alerts.
	409	DELETEA^XQ ALERT: Cle ar Obsolet e Alerts.
	410	SETUP^XQAL ERT: Send Alerts.
	411	$$SETUP1^X QALERT: Se nd Alerts.
	412	FORWARD^XQ ALFWD(): F orward Ale rts.
	413	REMVSURO^X QALSURO(): Remove Su rrogates f or Alerts.
	414	SUROLIST^X QALSURO(): List Surr ogates for a User.
	415	SETSURO1^X QALSURO(): Establish a Surroga te for Ale rts.
	416	GETIREF^XT ID(): Get IREF (Term /Concept).
	417	$$GETMASTR ^XTID(): G et Master VUID Flag (Term/Conc ept).
	418	$$GETSTAT^ XTID(): Ge t Status I nformation (Term/Con cept).
	419	$$GETVUID^ XTID(): Ge t VUID (Te rm/Concept ).
	420	$$SCREEN^X TID(): Get Screening Condition (Term/Con cept) API (ICR # 463 1).
	421	$$SETMASTR ^XTID(): S et Master VUID Flag (Term/Conc ept).
	422	$$SETSTAT^ XTID(): Se t Status I nformation (Term/Con cept).
	423	$$SETVUID^ XTID(): Se t VUID (Te rm/Concept ).
	424	$$IEN^XUPS (): Get IE N Using VP ID in File #200—Chan ged refere nces to IE NS to IEN.
	425	$$NNT^XUAF 4(): Insti tution Sta tion Name, Number, a nd Type—Ou tput order was previ ously inco rrect, sho uld be Nam e, Number, and type not Number , Name, an d Type.
	426	$$NODEV^XU TMDEVQ(): Force Queu ing—No Dev ice Select ion—Update d input pa rameters.
	427	$$OPTDE^XP DUTL(): Di sable/Enab le an Opti on.
	428	^%ZIS: Sta ndard Devi ce Call—Ad ded output parameter s.
	429	^%ZOSF(): Operating System-dep endent Log ic Global.
	430	General Up dates:
	431	Updated th e “Re-Inde xing Files ” section based on R emedy Tick et #63087.
	432	Updated re ferences t o the VDL.
	433	Updated th e “Alpha/B eta Tracki ng” sectio n in Secti on 14. Mer ged inform ation from the Kerne l Systems Management Guide int o the Kern el Develop er’s Guide (this man ual) in or der to avo id duplica tion and c onfusion w ith instru ctions/pro cedures.
	434	Removed al l but one reference to HSD&D; kept as a placeholde r for now.
	435	Removed ob solete ref erences to MSM, PDP, 486, VAX Alpha, etc . and chan ged/update d referenc es to DSM for OpenVM S to Caché where app ropriate.
	436	Software V ersions:
	437	Kernel 8.0
	438	Toolkit 7. 3
	439	OIFO:
	440	Maintenanc e Project Manager: J . Sch.
	441	Developers : G. B., A . C., W. F ., J. G., J. I., R. Men., R. M et., S. O. , and B. T .
	442	Technical Writer: T. B.
	443	02/08/2007
	444	5.0
	445	Merging th e Kernel T oolkit doc umentation set with the Kernel documenta tion set. Moving all Kernel To olkit cont ent to the appropria te Kernel manual and section.I n the Kern el Develop er’s Guide , the foll owing Kern el Toolkit APIs and Direct Mod e Utilitie s have bee n added to the new “ Toolkit” S ection:
	446	Toolkit—Al erts APIs
	447	Toolkit—Du plicate Re cord Merge APIs
	448	Toolkit—KE RMIT APIs
	449	Toolkit—Mu lti-Term L ook-Up (MT LU) APIs
	450	Toolkit—Pa rameter To ols APIs
	451	Toolkit—Vi stA XML Pa rser APIs
	452	Toolkit—VH A Unique I D (VUID) A PIs
	453	NOTE: Add ing Kernel Toolkit A PIs to the Kernel AP Is VA Intr anet Websi te in the near futur e.
	454	Added new National P rovider Id entifier ( NPI)-relat ed APIs se ction. API s released with Kern el patch X U8.0410:
	455	$$CHKDGT^X USNPI (ICR # 4532)
	456	$$NPI^XUSN PI (ICR # 4532)
	457	$$QI^XUSNP I (ICR # 4 532)
	458	$$TAXIND^X USTAX (ICR # 4911)
	459	$$TAXORG^X USTAX (ICR # 4911
	460	Added new Common Ser vices-rela ted APIs s ection. AP Is release d with Ker nel Patche s XU8.03 09 and 325 :
	461	$$VPID^XUP S (ICR # 4 574)
	462	$$IEN^XUPS (ICR # 45 74)
	463	EN1^XUPSQR Y (ICR # 4 575)
	464	Changed Ke rnel docum ent title references to:
	465	Kernel Dev eloper’s G uide (prev iously kno wn as the Kernel Pro grammer Ma nual).
	466	Kernel Sys tems Manag ement Guid e (previou sly known as the Ker nel System s Manual).
	467	Software V ersions:
	468	Kernel 8.0
	469	Toolkit 7. 3
	470	OIFO:
	471	Maintenanc e Project Manager: J . Sch.
	472	Developers : A. C., W . F., J. G ., J. I., M. M., R. Men., R. M et., S. O. and B. T.
	473	Technical Writer: T. B.
	474	06/20/2006
	475	4.1
	476	Updates:
	477	Corrected output arr ay subscri pt in the F4^XUAF4 A PI from “S TATION NUM ER” to “ST ATION NUMB ER (Remedy #HD000000 0147298).
	478	Updated do cument for mat to fol low latest Guideline s and SOP.
	479	Kernel 8.0
	480	OIFO:
	481	Maintenanc e Project Manager: J . Sch.
	482	Developer: R. Met.
	483	Technical Writer: T. B.
	484	01/23/2006
	485	4.0
	486	I Updates:
	487	$$QQ^XUTMD EVQ, updat ed descrip tion (XU8 .0389).
	488	Changed RE QQ^XUTMDEV Q to $$REQ Q^XUTMDEVQ ; updated descriptio n (XU8.0 389).
	489	Updated RE Q^%ZTLOAD and ^%ZTLO AD APIs.
	490	Changed $$ SENTCASE^X LFSTR to $ $SENTENCE^ XLFSTR (XU 8.0400).
	491	Kernel 8.0
	492	OIFO:
	493	Maintenanc e Project Manager: J . Sch.
	494	Developer: G. B. and W. F.
	495	Technical Writer: T. B.
	496	12/15/2005
	497	3.8
	498	Added the following APIs (via patches cu rrently no t yet rele ased):
	499	$$CREATE^X USAP (XU8 .0361)
	500	$$SENTCASE ^XLFSTR (X U8.0400)
	501	$$TITLE^XL FSTR (XU8 .0400)
	502	Changed Jo b^%ZTLOAD to $$JOB^% ZTLOAD
	503	Kernel 8.0
	504	OIFO:
	505	Maintenanc e Project Manager: J . Sch.
	506	Developer: W. F.
	507	Technical Writer: T. B.
	508	10/19/2005
	509	3.7
	510	Updated th e SETUP^XQ ALERT API based on f eedback fr om the use r communit y and deve lopers.
	511	Kernel 8.0
	512	OIFO:
	513	Maintenanc e Project Manager: J . Sch.
	514	Developers : W. F. an d J. I.
	515	Technical Writer: T. B.
	516	09/28/2005
	517	3.6
	518	Added the $$HANDLE^X USRB4 and REQQ^XUTMD EVQ APIs.
	519	Kernel 8.0
	520	OIFO:
	521	Maintenanc e Project Manager: J . Sch.
	522	Developer: W. F.
	523	Technical Writer: T. B.
	524	09/22/2005
	525	3.5
	526	Updated AP Is:
	527	SETUP^XQAL ERT
	528	SETUP^XUSR B
	529	OWNSKEY^XU SRB
	530	DQ^%ZTLOAD
	531	ISQED^%ZTL OAD
	532	KILL^%ZTLO AD
	533	PCLEAR^%ZT LOAD
	534	STAT^%ZTLO AD
	535	Added APIs :
	536	ASKSTOP^%Z TLOAD
	537	DESC^%ZTLO AD
	538	JOB^%ZTLOA D
	539	OPTION^%ZT LOAD
	540	$$PSET^%ZT LOAD
	541	RTN^%ZTLOA D
	542	$$S^%ZTLOA D
	543	ZTSAVE^%ZT LOAD
	544	Kernel 8.0
	545	OIFO:
	546	Maintenanc e Project Manager: J . Sch.
	547	Developer: W. F. and J. I.
	548	Technical Writer: T. B.
	549	04/14/2005
	550	3.4
	551	Categorize d CRC XLF functions into a new category (i.e., “CR C” vs. “Ot her”).
	552	Kernel 8.0
	553	OIFO:
	554	Maintenanc e Project Manager: J . Sch.
	555	Technical Writer: T. B.
	556	03/02/2005
	557	3.3
	558	Corrected various AP Is. Reorde red all AP Is under e ach catego ry: 1) by routine na me and 2) by tag nam e.
	559	Kernel 8.0
	560	OIFO:
	561	Maintenanc e Project Manager: J . Sch.
	562	Technical Writer: T. B.
	563	02/10/2005
	564	3.2
	565	Updates:
	566	^%ZTLOAD: Queue a Ta sk
	567	REQ^%ZTLOA D: Requeue a Task
	568	Added thre e new XUTM DEVQ APIs (Kernel pa tch XU8.0 275).
	569	Kernel 8.0
	570	OIFO:
	571	Maintenanc e Project Manager: J . Sch.
	572	Developers : G. B. an d W. F.
	573	Technical Writer—: T . B.
	574	12/20/2004
	575	3.1
	576	Reviewed d ocument an d edited f or the “Da ta Scrubbi ng” and th e “PDF 508 Complianc e” project s.
	577	Data Scrub bing—Chang ed all pat ient/user TEST data to conform to OI&T s tandards a nd convent ions as in dicated be low:
	578	The first three digi ts (prefix ) of any S ocial Secu rity Numbe rs (SSN) s tart with “000” or “ 666.”
	579	Format pat ient or us er names a s follows: XUPATIENT ,[N] or XU USER,[N] r espectivel y, where t he N is a number wri tten out a nd increme nted with each new e ntry (e.g. , XUPATIEN T, ONE, XU PATIENT, T WO, etc.).
	580	Changed ot her person al demogra phic-relat ed data (e .g., addre sses, phon es, IP add resses, et c.) to be generic.
	581	PDF 508 Co mpliance—T he final P DF documen t was recr eated and now suppor ts the min imum requi rements to be 508 co mpliant (i .e., acces sibility t ags, langu age select ion, alter nate text for all im ages/icons , fully fu nctional W eb links, successful ly passed Adobe Acro bat Quick Check).
	582	Kernel 8.0
	583	OIFO:
	584	Maintenanc e Project Manager: J . Sch.
	585	Technical Writer: T. B.
	586	12/09/2004
	587	3.0
	588	Updated va rious APIs based on developer feedback. Also, maki ng minor e dits as we begin pop ulating th e HTML ver sions of t he APIs.
	589	Kernel 8.0
	590	OIFO:
	591	Maintenanc e Project Manager: J . Sch.
	592	Developer: W. F.
	593	Technical Writer: T. B.
	594	12/24/2003
	595	2.0
	596	Kernel 8.0 documenta tion refor matting/re vision.
	597	This is th e initial Kernel Dev eloper’s G uide. Crea ted this m anual by e xtracting all develo per-specif ic content from the Kernel Sys tems Manag ement Guid e (origina l release date of Ju ly 1995).
	598	The Kernel Developer ’s Guide I ncludes ad ded/update d Direct M ode Utilit ies and Ap plication Programmin g Interfac e (API) in formation (e.g., Ref erence Typ e, Categor y, Integra tion Contr ol Registr ation numb er. etc.). It also i ncludes AP Is for pre vious Kern el APIs ne ver before documente d (i.e., i ncludes AP Is that we re previou sly only d ocumented in patch d escription s, Integra tion Contr ol Registr ations, or separate supplement al documen tation).
	599	NOTE: Thi s manual a lso includ es the Ker nel Toolki t APIs.
	600	Due to tim e constrai nts, not a ll release d Kernel p atches wit h develope r-related content ch anges have been adde d at this time. Also , there is known mis sing infor mation tha t will be added/upda ted at a f uture date . We wante d to get a new basel ine docume nt publish ed so that in the fu ture we ca n more eas ily update the Kerne l Develope r’s Guide.
	601	As time al lows, we w ill be upd ating this manual wi th all rel eased patc h informat ion that a ffects its content.
	602	Kernel 8.0
	603	OIFO:
	604	Maintenanc e Project Manager: J . Sch.
	605	Developers : Kernel D evelopment Team
	606	Technical Writer: T. B.
	607	07/1995
	608	1.0
	609	Initial Ke rnel 8.0 s oftware an d document ation rele ase.
	610	Kernel 8.0
	611	Office of Informatio n field Of fice (OIFO ):
	612	Project Ma nager: H. V. B.
	613	Developers : Kernel D evelopment Team
	614	Technical Writer: K. C.
	615
	616	Patch Revi sions
	617	For the cu rrent patc h history related to this soft ware, see the Patch Module on FORUM.
	618
	619	Table of C ontents
	620
	621	Revision H istoryii
	622	List of Fi guresliii
	623	List of Ta bleslviii
	624	Orientatio nlx
	625	1Introduct ion1
	626	2Address H ygiene: De veloper To ols3
	627	2.1Applica tion Progr amming Int erface (AP I)3
	628	2.1.1CCODE ^XIPUTIL() : FIPS Cod e Data3
	629	2.1.1.1Exa mple4
	630	2.1.2$$FIP S^XIPUTIL( ): FIPS Co de for ZIP Code4
	631	2.1.2.1Exa mple4
	632	2.1.3$$FIP SCHK^XIPUT IL(): Chec k for FIPS Code5
	633	2.1.3.1Exa mples5
	634	2.1.4POSTA L^XIPUTIL( ): ZIP Cod e Informat ion5
	635	2.1.4.1Exa mples7
	636	2.1.5POSTA LB^XIPUTIL (): Active ZIP Codes 8
	637	2.1.5.1Exa mple9
	638	3Alerts: D eveloper T ools10
	639	3.1Overvie w10
	640	3.2Package Identifie r vs. Aler t Identifi er11
	641	3.2.1Packa ge Identif ier11
	642	3.2.2Alert Identifie r11
	643	3.3Package Identifie r Conventi ons11
	644	3.4Glossar y of Terms for Alert s12
	645	3.5Applica tion Progr amming Int erface (AP I)13
	646	3.5.1AHIST ORY^XQALBU TL(): Get Alert Trac king File Informatio n13
	647	3.5.1.1Exa mple14
	648	3.5.2ALERT DAT^XQALBU TL(): Get Alert Trac king File Informatio n15
	649	3.5.2.1Exa mple16
	650	3.5.3DELST AT^XQALBUT L():Get Re cipient In formation and Alert Status16
	651	3.5.3.1Exa mple17
	652	3.5.4NOTIP URG^XQALBU TL(): Purg e Alerts B ased on Co de17
	653	3.5.5$$PEN DING^XQALB UTL(): Pen ding Alert s for a Us er18
	654	3.5.5.1Exa mples18
	655	3.5.6$$PKG PEND^XQALB UTL(): Pen ding Alert s for a Us er in Spec ified Soft ware19
	656	3.5.6.1Exa mples19
	657	3.5.7PTPUR G^XQALBUTL (): Purge Alerts Bas ed on Pati ent20
	658	3.5.8RECIP URG^XQALBU TL(): Purg e User Ale rts20
	659	3.5.9USERD ATA^XQALBU TL(): Get User Infor mation for an Alert2 1
	660	3.5.9.1Exa mple21
	661	3.5.10USER LIST^XQALB UTL(): Get Recipient Informati on for an Alert22
	662	3.5.10.1Ex ample22
	663	3.5.11ACTI ON^XQALERT (): Proces s an Alert 22
	664	3.5.12DELE TE^XQALERT : Clear Ob solete Ale rts23
	665	3.5.13DELE TEA^XQALER T: Clear O bsolete Al erts24
	666	3.5.14GETA CT^XQALERT (): Return Alert Var iables25
	667	3.5.15PATI ENT^XQALER T(): Get A lerts for a Patient2 6
	668	3.5.16SETU P^XQALERT: Send Aler ts27
	669	3.5.16.1De tails—When the Alert is Proces sed30
	670	3.5.16.2Ex ample31
	671	3.5.17$$SE TUP1^XQALE RT: Send A lerts31
	672	3.5.17.1De tails—When the Alert is Proces sed34
	673	3.5.17.2Ex ample35
	674	3.5.18USER ^XQALERT() : Get Aler ts for a U ser36
	675	3.5.18.1Ex ample37
	676	3.5.19FORW ARD^XQALFW D(): Forwa rd Alerts3 7
	677	3.5.19.1Ex ample38
	678	3.5.20$$CU RRSURO^XQA LSURO(): G et Current Surrogate for Alert s39
	679	3.5.21$$GE TSURO^XQAL SURO(): Ge t Current Surrogate Informatio n39
	680	3.5.21.1Ex ample40
	681	3.5.22REMV SURO^XQALS URO(): Rem ove Surrog ates for A lerts40
	682	3.5.23SETS URO1^XQALS URO(): Est ablish a S urrogate f or Alerts4 1
	683	3.5.23.1Ex ample42
	684	3.5.24SURO FOR^XQALSU RO(): Retu rn a Surro gate’s Lis t of Users 42
	685	3.5.24.1Ex ample43
	686	3.5.25SURO LIST^XQALS URO(): Lis t Surrogat es for a U ser43
	687	3.5.25.1Ex ample44
	688	4Common Se rvices: De veloper To ols45
	689	4.1Applica tion Progr amming Int erface (AP I)45
	690	4.1.1$$IEN ^XUPS(): G et IEN Usi ng VPID in File #200 45
	691	4.1.2$$VPI D^XUPS(): Get VPID U sing IEN i n File #20 045
	692	4.1.3EN1^X UPSQRY(): Query New Person Fil e46
	693	5Data Secu rity: Deve loper Tool s48
	694	5.1Overvie w48
	695	5.2Applica tion Progr amming Int erface (AP I)48
	696	5.2.1$$AES DECR^XUSHS H(): Retur ns Plainte xt String Value for AES Encryp ted Cipher text Entry 48
	697	5.2.1.1Exa mple49
	698	5.2.2$$AES ENCR^XUSHS H(): Retur ns AES Enc rypted Cip hertext fo r String E ntry49
	699	5.2.2.1Exa mple49
	700	5.2.3$$B64 DECD ^XUSH SH(): Retu rns Decode d Value fo r a Base64 String En try50
	701	5.2.3.1Exa mple50
	702	5.2.4$$B64 ENCD^XUSHS H(): Retur ns Base64 Encoded Va lue for a String Ent ry50
	703	5.2.4.1Exa mple51
	704	5.2.5$$RSA DECR^XUSHS H(): Retur ns Plainte xt String Value for RSA Encryp ted Cipher text Entry 51
	705	5.2.5.1Exa mple51
	706	5.2.6$$RSA ENCR^XUSHS H(): Retur ns RSA Enc rypted Cip hertext fo r String E ntry52
	707	5.2.6.1Exa mple53
	708	5.2.7$$SHA HASH^XUSHS H(): Retur ns SHA Has h for a St ring Entry 53
	709	5.2.7.1Exa mples54
	710	6Device Ha ndler: Dev eloper Too ls55
	711	6.1Overvie w55
	712	6.2Applica tion Progr amming Int erface (AP I)55
	713	6.2.1DEVIC E^XUDHGUI( ): GUI Dev ice Lookup 55
	714	6.2.1.1Exa mples56
	715	6.2.2$$RES ^XUDHSET() : Set Up R esource De vice58
	716	6.2.3^%ZIS : Standard Device Ca ll58
	717	6.2.3.1Exa mples66
	718	6.2.3.2Mul tiple Devi ces and ^% ZIS68
	719	6.2.3.3Hos t Files an d ^%ZIS68
	720	6.2.4HLP1^ %ZIS: Disp lay Brief Device Hel p68
	721	6.2.5HLP2^ %ZIS: Disp lay Device Help Fram es69
	722	6.2.6HOME^ %ZIS: Rese t Home Dev ice IO Var iables69
	723	6.2.7$$REW IND^%ZIS() : Rewind D evices70
	724	6.2.7.1Exa mple70
	725	6.2.8^%ZIS C: Close D evice71
	726	6.2.8.1Exa mple71
	727	6.2.9PKILL ^%ZISP: Ki ll Special Printer V ariables71
	728	6.2.10PSET ^%ZISP: Se t Up Speci al Printer Variables 72
	729	6.2.10.1Ex ample72
	730	6.2.11ENDR ^%ZISS: Se t Up Speci fic Screen Handling Variables7 3
	731	6.2.12ENS^ %ZISS: Set Up Screen -handling Variables7 4
	732	6.2.13GKIL L^%ZISS: K ILL Graphi c Variable s78
	733	6.2.14GSET ^%ZISS: Se t Up Graph ic Variabl es78
	734	6.2.14.1Ex ample79
	735	6.2.15KILL ^%ZISS: KI LL Screen Handling V ariables79
	736	6.2.16CALL ^%ZISTCP: Make TCP/I P Connecti on (Remote System)79
	737	6.2.17CLOS E^%ZISTCP: Close TCP /IP Connec tion (Remo te System) 80
	738	6.2.18CLOS E^%ZISUTL( ): Close D evice with Handle81
	739	6.2.19OPEN ^%ZISUTL() : Open Dev ice with H andle81
	740	6.2.19.1Ex ample83
	741	6.2.20RMDE V^%ZISUTL( ): Delete Data Given a Handle8 3
	742	6.2.21SAVD EV^%ZISUTL (): Save D ata Given a Handle84
	743	6.2.22USE^ %ZISUTL(): Use Devic e Given a Handle84
	744	6.3Special Device Is sues84
	745	6.3.1Form Feeds85
	746	6.3.1.1How to Check if Current Device is a CRT85
	747	6.3.1.2Gui delines fo r Form Iss uing Form Feeds85
	748	6.3.2Resou rces87
	749	6.3.2.1Que uing to a Resource87
	750	7Domain Na me Service (DNS): De veloper To ols88
	751	7.1Applica tion Progr amming Int erface (AP I)88
	752	7.1.1$$ADD RESS^XLFNS LK(): Conv ert Domain Name to I P Addresse s88
	753	7.1.1.1Exa mples88
	754	7.1.2MAIL^ XLFNSLK(): Get IP Ad dresses fo r a Domain Name89
	755	7.1.2.1Exa mples89
	756	8Electroni c Signatur es: Develo per Tools9 0
	757	8.1Applica tion Progr amming Int erface (AP I)90
	758	8.1.1^XUSE SIG: Set U p Electron ic Signatu re Code90
	759	8.1.2SIG^X USESIG(): Verify Ele ctronic Si gnature Co de90
	760	8.1.3$$CHK SUM^XUSESI G1(): Buil d Checksum for Globa l Root91
	761	8.1.4$$CMP ^XUSESIG1( ): Compare Checksum to $Name_V alue91
	762	8.1.5$$DE^ XUSESIG1() : Decode S tring92
	763	8.1.6$$EN^ XUSESIG1() : Encode E SBLOCK92
	764	8.1.7$$ESB LOCK^XUSES IG1(): E-S ig Fields Required f or Hash92
	765	8.1.8DE^XU SHSHP: Dec rypt Data String93
	766	8.1.9EN^XU SHSHP: Enc rypt Data String94
	767	8.1.10HASH ^XUSHSHP: Hash Elect ronic Sign ature Code 94
	768	9Error Pro cessing: D eveloper T ools96
	769	9.1Direct Mode Utili ties96
	770	9.1.1>D ^X TER96
	771	9.1.2>D ^X TERPUR96
	772	9.2Applica tion Progr amming Int erface (AP I)96
	773	9.2.1$$EC^ %ZOSV: Get Error Cod e96
	774	9.2.1.1Exa mple96
	775	9.2.2^%ZTE R: Kernel Standard E rror Recor ding Routi ne97
	776	9.2.2.1Exa mple98
	777	9.2.3$$APP ERR^%ZTER: Set Appli cation Err or Name in Kernel Er ror Trap L og99
	778	9.2.3.1Exa mple99
	779	9.2.4$$NEW ERR^%ZTER: Verify Su pport of S tandard Er ror Trappi ng (Obsole te)99
	780	9.2.5UNWIN D^%ZTER: Q uit Back t o Calling Routine100
	781	9.2.5.1Exa mple100
	782	10Field Mo nitoring: Developer Tools101
	783	10.1Applic ation Prog ramming In terface (A PI)101
	784	10.1.1OPKG ^XUHUI(): Monitor Ne w Style Cr oss-refere nced Field s101
	785	10.1.1.1Ex ample101
	786	11File Acc ess Securi ty: Develo per Tools1 06
	787	11.1Overvi ew106
	788	11.2Field Level Prot ection106
	789	11.3File N avigation1 06
	790	11.4Use of DLAYGO Wh en Navigat ing to Fil es106
	791	11.5Use of DLAYGO in ^DIC Call s107
	792	11.6Use of DIDEL in ^DIE Calls 107
	793	12Help Pro cessor: De veloper To ols109
	794	12.1Entry and Exit E xecute Sta tements109
	795	12.2Applic ation Prog ramming In terface (A PI)109
	796	12.2.1EN^X QH: Displa y Help Fra mes109
	797	12.2.2EN1^ XQH: Displ ay Help Fr ames109
	798	12.2.3ACTI ON^XQH4(): Print Hel p Frame Tr ee110
	799	13Host Fil es: Develo per Tools1 11
	800	13.1Applic ation Prog ramming In terface (A PI)111
	801	13.1.1CLOS E^%ZISH(): Close Hos t File112
	802	13.1.1.1Ex ample112
	803	13.1.2$$DE FDIR^%ZISH (): Get De fault Host File Dire ctory112
	804	13.1.3$$DE L^%ZISH(): Delete Ho st File113
	805	13.1.3.1Ex ample113
	806	13.1.4$$FT G^%ZISH(): Load Host File into Global114
	807	13.1.4.1Ex ample115
	808	13.1.5$$GA TF^%ZISH() : Copy Glo bal to Hos t File115
	809	13.1.6$$GT F^%ZISH(): Copy Glob al to Host File116
	810	13.1.6.1Ex ample116
	811	13.1.7$$LI ST^%ZISH() : List Dir ectory116
	812	13.1.7.1Ex ample117
	813	13.1.8$$MV ^%ZISH(): Rename Hos t File117
	814	13.1.8.1Ex ample118
	815	13.1.9OPEN ^%ZISH(): Open Host File118
	816	13.1.9.1Ex ample119
	817	13.1.10$$P WD^%ZISH: Get Curren t Director y119
	818	13.1.10.1E xample119
	819	13.1.11$$S TATUS^%ZIS H: Return End-of-Fil e Status11 9
	820	13.1.11.1E xample120
	821	14Institut ion File: Developer Tools121
	822	14.1Applic ation Prog ramming In terface (A PI)121
	823	14.1.1$$AC TIVE^XUAF4 (): Instit ution Acti ve Facilit y (True/Fa lse)121
	824	14.1.2CDSY S^XUAF4(): Coding Sy stem Name1 21
	825	14.1.3CHIL DREN^XUAF4 (): List o f Child In stitutions for a Par ent122
	826	14.1.4$$CI RN^XUAF4() : Institut ion CIRN-e nabled Fie ld Value12 2
	827	14.1.5F4^X UAF4(): In stitution Data for a Station N umber123
	828	14.1.5.1Ex ample124
	829	14.1.6$$ID ^XUAF4(): Institutio n Identifi er124
	830	14.1.7$$ID X^XUAF4(): Instituti on IEN (Us ing Coding System & ID)124
	831	14.1.8$$IE N^XUAF4(): IEN for S tation Num ber125
	832	14.1.8.1Ex ample125
	833	14.1.9$$LE GACY^XUAF4 (): Instit ution Real igned/Lega cy (True/F alse)125
	834	14.1.10$$L KUP^XUAF4( ): Institu tion Looku p126
	835	14.1.11LOO KUP^XUAF4( ): Look Up Instituti on Identif ier126
	836	14.1.11.1E xample127
	837	14.1.12$$M ADD^XUAF4( ): Institu tion Maili ng Address 127
	838	14.1.13$$N AME^XUAF4( ): Institu tion Offic ial Name12 7
	839	14.1.14$$N NT^XUAF4() : Institut ion Statio n Name, Nu mber, and Type128
	840	14.1.15$$N S^XUAF4(): Instituti on Name an d Station Number128
	841	14.1.16$$O 99^XUAF4() : IEN of M erged Stat ion Number 129
	842	14.1.16.1E xample129
	843	14.1.17$$P ADD^ XUAF4 (): Instit ution Phys ical Addre ss129
	844	14.1.18PAR ENT^XUAF4( ): Parent Institutio n Lookup13 0
	845	14.1.19$$P RNT^XUAF4( ): Institu tion Paren t Facility 130
	846	14.1.20$$R F^XUAF4(): Realigned From Inst itution In formation1 31
	847	14.1.20.1E xample131
	848	14.1.21$$R T^XUAF4(): Realigned To Instit ution Info rmation131
	849	14.1.21.1E xample132
	850	14.1.22SIB LING^XUAF4 (): Siblin g Institut ion Lookup 132
	851	14.1.23$$S TA^XUAF4() : Station Number for IEN133
	852	14.1.23.1E xample133
	853	14.1.24$$T F^XUAF4(): Treating Facility ( True/False )133
	854	14.1.24.1E xample133
	855	14.1.25$$W HAT^XUAF4( ): Institu tion Singl e Field In formation1 34
	856	14.1.26$$I EN^XUMF(): Instituti on IEN (Us ing IFN, C oding Syst em, & ID)1 34
	857	14.1.27MAI N^XUMFI(): HL7 Maste r File Mes sage Build er135
	858	14.1.27.1D etails135
	859	14.1.27.2E xample135
	860	14.1.28MAI N^XUMFP(): Master Fi le Paramet ers136
	861	14.1.28.1D etails137
	862	14.1.28.2E xample140
	863	15Kernel I nstallatio n and Dist ribution S ystem (KID S): Develo per Tools1 42
	864	15.1KIDS B uild-relat ed Options 142
	865	15.2Creati ng Builds1 43
	866	15.2.1Buil d Entries1 43
	867	15.2.2Crea te a Build Using Nam espace144
	868	15.2.3Copy Build to Build145
	869	15.2.4Edit a Build14 6
	870	15.2.4.1KI DS Build S creens146
	871	15.2.4.2Ed it a Build : Name & V ersion, Bu ild Inform ation147
	872	15.2.4.3Ed it a Build : Files148
	873	15.2.4.4Ed it a Build : Componen ts156
	874	15.2.4.5Ed it a Build : Options and Protoc ols157
	875	15.2.4.6Ed it a Build : Routines 158
	876	15.2.4.7Ed it a Build : Dialog E ntries (DI ALOG File [#.84])159
	877	15.2.4.8Ed it a Build : Forms159
	878	15.2.4.9Ed it a Build : Template s160
	879	15.2.5Tran sporting a Distribut ion160
	880	15.2.5.1Wh en to Tran sport More than One Transport Global in a Distribu tion162
	881	15.2.5.2Mu lti-Packag e Builds16 3
	882	15.2.5.3Ex porting Gl obals with KIDS163
	883	15.2.6Crea ting Trans port Globa ls that In stall Effi ciently164
	884	15.3Advanc ed Build T echniques1 65
	885	15.3.1Envi ronment Ch eck Routin e165
	886	15.3.1.1Se lf-Contain ed Routine 165
	887	15.3.1.2En vironment Check is R un Twice16 5
	888	15.3.1.3Ke y Variable s during E nvironment Check166
	889	15.3.1.4Pa ckage Vers ion vs. In stalling V ersion167
	890	15.3.1.5Te lling KIDS to Skip I nstalling or Delete a Routine1 67
	891	15.3.1.6Ve rifying Pa tch Instal lation167
	892	15.3.1.7Ab orting Ins tallations During th e Environm ent Check1 67
	893	15.3.1.8Co ntrolling the Queuin g of the I nstall Pro mpt168
	894	15.3.1.9Co ntrolling the Disabl e Options/ Protocols Prompt168
	895	15.3.1.10C ontrolling the Move Routines t o Other CP Us Prompt1 69
	896	15.3.2PRE- TRANSPORTA TION ROUTI NE field ( #900)170
	897	15.3.3Pre- and Post- Install Ro utines: Sp ecial Feat ures171
	898	15.3.3.1Ab orting an Installati on During the Pre-In stall Rout ine171
	899	15.3.3.2Se tting a Fi le’s Packa ge Revisio n Data Nod e (Post-In stall)172
	900	15.3.3.3Ke y Paramete rs during Pre- and P ost-Instal l Routines 172
	901	15.3.3.4Ke y Variable s during P re- and Po st-Install Routines1 72
	902	15.3.3.5NE W the DIFR OM Variabl e When Cal ling MailM an173
	903	15.3.3.6Up date the S tatus Bar During Pre - and Post -Install R outines173
	904	15.3.4Edit a Build—S creen 4174
	905	15.3.5How to Ask Ins tallation Questions1 74
	906	15.3.5.1Qu estion Sub scripts175
	907	15.3.5.2M Code in Qu estions175
	908	15.3.5.3Sk ipping Ins tallation Questions1 75
	909	15.3.5.4Ac cessing Qu estions an d Answers1 75
	910	15.3.5.5Wh ere Questi ons Are As ked During Installat ions176
	911	15.3.6Usin g Checkpoi nts (Pre- and Post-I nstall Rou tines)176
	912	15.3.6.1Ch eckpoints with Callb acks177
	913	15.3.6.2Ch eckpoint P arameter N ode178
	914	15.3.6.3Ch eckpoints without Ca llbacks (D ata Storag e)180
	915	15.3.7Requ ired Build s181
	916	15.3.8Pack age File L ink182
	917	15.3.9Trac k Package Nationally 183
	918	15.3.10Alp ha/Beta Tr acking184
	919	15.3.10.1I nitiating Alpha/Beta Tracking1 85
	920	15.3.10.2E rror Track ing—Alpha/ Beta Softw are Releas es186
	921	15.3.10.3M onitoring Alpha/Beta Tracking1 87
	922	15.3.10.4T erminating Alpha/Bet a Tracking 188
	923	15.4Applic ation Prog ramming In terface (A PI)190
	924	15.4.1UPDA TE^XPDID() : Update I nstall Pro gress Bar1 90
	925	15.4.1.1Ex ample190
	926	15.4.2EN^X PDIJ(): Ta sk Off KID S Install1 91
	927	15.4.3$$PK GPAT^XPDIP (): Update Patch His tory191
	928	15.4.4BMES ^XPDUTL(): Output a Message wi th Blank L ine192
	929	15.4.5$$CO MCP^XPDUTL (): Comple te Checkpo int192
	930	15.4.6$$CU RCP^XPDUTL (): Get Cu rrent Chec kpoint Nam e/IEN193
	931	15.4.7$$IN STALDT^XPD UTL(): Ret urn All In stall Date s/Times193
	932	15.4.7.1Ex ample194
	933	15.4.8$$LA ST^XPDUTL( ): Last So ftware Pat ch194
	934	15.4.8.1Ex amples195
	935	15.4.9MES^ XPDUTL(): Output a M essage195
	936	15.4.10$$N EWCP^XPDUT L(): Creat e Checkpoi nt196
	937	15.4.11$$O PTDE^XPDUT L(): Disab le/Enable an Option1 97
	938	15.4.11.1E xample197
	939	15.4.12$$P ARCP^XPDUT L(): Get C heckpoint Parameter1 97
	940	15.4.13$$P ATCH^XPDUT L(): Verif y Patch In stallation 198
	941	15.4.13.1E xample198
	942	15.4.14$$P KG^XPDUTL( ): Parse S oftware Na me from Bu ild Name19 8
	943	15.4.15$$P RODE^XPDUT L(): Disab le/Enable a Protocol 199
	944	15.4.16$$R TNUP^XPDUT L(): Updat e Routine Action199
	945	15.4.17$$U PCP^XPDUTL (): Update Checkpoin t200
	946	15.4.18$$V ER^XPDUTL( ): Parse V ersion fro m Build Na me200
	947	15.4.19$$V ERCP^XPDUT L(): Verif y Checkpoi nt201
	948	15.4.20$$V ERSION^XPD UTL(): Pac kage File Current Ve rsion201
	949	16Lock Man ager: Deve loper Tool s202
	950	16.1Applic ation Prog ramming In terface (A PI)—Housek eeping202
	951	16.1.1CLEA NUP^XULMU( ): Execute the House cleaning S tack202
	952	16.1.1.1Ex amples202
	953	16.1.2SETC LEAN^XULMU (): Regist er a Clean up Routine 203
	954	16.1.2.1Ex ample203
	955	16.1.3UNCL EAN^XULMU( ): Remove Entries fr om the Hou secleaning Stack204
	956	16.1.3.1Ex amples204
	957	16.2Applic ation Prog ramming In terface (A PI)—Lock D ictionary2 05
	958	16.2.1ADDP AT^XULMU() : Add Pati ent Identi fiers for a Computab le File Re ference205
	959	16.2.2PAT^ XULMU(): G et a Stand ard Set of Patient I dentifiers 205
	960	16.2.2.1Ex ample206
	961	17Menu Man ager: Deve loper Tool s207
	962	17.1Creati ng Options 207
	963	17.1.1Opti on Types20 7
	964	17.1.2Crea ting Optio ns (Edit O ptions)207
	965	17.1.2.1Op tions that Should Be Regularly Scheduled 208
	966	17.2Variab les for De veloper Us e208
	967	17.2.1XQUI T: Quit th e Option20 8
	968	17.2.2XQMM (“A”): Men u Prompt20 8
	969	17.2.3XQMM (“B”): Def ault Respo nse208
	970	17.2.4XQMM (“J”): The Phantom J ump209
	971	17.2.5XQMM (“N”): No Menu Displ ay209
	972	17.3Direct Mode Util ities209
	973	17.3.1^XQ1 : Test an Option209
	974	17.4Applic ation Prog ramming In terface (A PI)210
	975	17.4.1$$AD D^XPDMENU( ): Add Opt ion to Men u210
	976	17.4.2$$DE LETE^XPDME NU(): Dele te Menu It em210
	977	17.4.3$$LK OPT^XPDMEN U(): Look Up Option IEN211
	978	17.4.4OUT^ XPDMENU(): Edit Opti on’s Out o f Order Me ssage211
	979	17.4.5RENA ME^XPDMENU (): Rename Option212
	980	17.4.6$$TY PE^XPDMENU (): Get Op tion Type2 12
	981	17.4.7$$AD D^XPDPROT( ): Add Chi ld Protoco l to Paren t Protocol 213
	982	17.4.8$$DE LETE^XPDPR OT(): Dele te Child P rotocol fr om Parent Protocol21 4
	983	17.4.9FIND ^XPDPROT() : Find All Parents f or a Proto col214
	984	17.4.10$$L KPROT^XPDP ROT(): Loo k Up Proto col IEN215
	985	17.4.11OUT ^XPDPROT() : Edit Pro tocol’s Ou t of Order Message21 5
	986	17.4.12REN AME^XPDPRO T(): Renam e Protocol 216
	987	17.4.13$$T YPE^XPDPRO T(): Get P rotocol Ty pe217
	988	17.4.14NEX T^XQ92(): Restricted Times Che ck218
	989	17.4.15$$A CCESS^XQCH K(): User Option Acc ess Test21 8
	990	17.4.16OP^ XQCHK(): C urrent Opt ion Check2 19
	991	17.4.16.1E xamples220
	992	18Miscella neous: Dev eloper Too ls221
	993	18.1Direct Mode Util ities221
	994	18.2Progra mmer Optio ns Menu221
	995	18.2.1Dele te Unrefer enced Opti ons221
	996	18.2.2Glob al Block C ount Optio n221
	997	18.2.3List ing Global s Option22 2
	998	18.2.4Test an option not in yo ur menu Op tion222
	999	18.3^%Z Ed itor222
	1000	18.3.1User Interface 222
	1001	18.4Applic ation Prog ramming In terface (A PI)225
	1002	18.4.1Prog ress Bar E mulator225
	1003	18.4.1.1IN IT^XPDID: Progress B ar Emulato r: Initial ize Device and Draw Box Border s225
	1004	18.4.1.2TI TLE^XPDID( ): Progres s Bar Emul ator: Disp lay Title Text225
	1005	18.4.1.3EX IT^XPDID() : Progress Bar Emula tor: Resto re Screen, Clean Up Variables, and Displ ay Text226
	1006	18.4.2Look up Utility 226
	1007	18.4.2.1$$ EN^XUA4A71 (): Conver t String t o Soundex2 26
	1008	18.4.3Date Conversio ns and Cal culations2 27
	1009	18.4.3.1^X QDATE: Con vert $H to VA FileMa n Format ( Obsolete)2 27
	1010	18.4.3.2^X UWORKDY: W orkday Cal culation ( Obsolete)2 27
	1011	18.4.3.3Ex ample228
	1012	18.4.3.4$$ EN^XUWORKD Y: Number of Workday s Calculat ion229
	1013	18.4.3.5Ex ample229
	1014	18.4.3.6$$ WORKDAY^XU WORKDY: Wo rkday Vali dation230
	1015	18.4.3.7Ex amples230
	1016	18.4.3.8$$ WORKPLUS^X UWORKDY: W orkday Off set Calcul ation231
	1017	18.4.3.9Ex ample231
	1018	19Name Sta ndardizati on: Develo per Tools2 32
	1019	19.1Applic ation Prog ramming In terface (A PI)232
	1020	19.1.1$$BL DNAME^XLFN AME(): Bui ld Name fr om Compone nt Parts23 2
	1021	19.1.1.1De tails233
	1022	19.1.1.2Ex amples233
	1023	19.1.2$$CL EANC^XLFNA ME(): Name Component Standardi zation Rou tine234
	1024	19.1.2.1Ex amples235
	1025	19.1.3$$FM NAME^XLFNA ME(): Conv ert HL7 Fo rmatted Na me to Name 236
	1026	19.1.3.1De tails236
	1027	19.1.3.2Ex amples237
	1028	19.1.4$$HL NAME^XLFNA ME(): Conv ert Name t o HL7 Form atted Name 238
	1029	19.1.4.1De tails239
	1030	19.1.4.2Ex amples239
	1031	19.1.5NAME COMP^XLFNA ME(): Comp onent Part s from Sta ndard Name 240
	1032	19.1.5.1Ex ample241
	1033	19.1.6$$NA MEFMT^XLFN AME(): For matted Nam e from Nam e Componen ts241
	1034	19.1.6.1De tails242
	1035	19.1.6.2Ex amples243
	1036	19.1.7STDN AME^XLFNAM E(): Name Standardiz ation Rout ine245
	1037	19.1.7.1De tails248
	1038	19.1.7.2Ex ample250
	1039	19.1.8DELC OM P^XLFNA ME2(): Del ete Name C omponents Entry250
	1040	19.1.8.1Ex ample251
	1041	19.1.9UPDC OMP^XLFNAM E2(): Upda te Name Co mponents E ntry251
	1042	19.1.9.1Ex ample252
	1043	20National Provider Identifier (NPI): De veloper To ols254
	1044	20.1Applic ation Prog ramming In terface (A PI)254
	1045	20.1.1$$CH KDGT^XUSNP I(): Valid ate NPI Fo rmat254
	1046	20.1.1.1Ex amples254
	1047	20.1.2$$NP I^XUSNPI() : Get NPI from Files #200 or # 4255
	1048	20.1.2.1Ex amples255
	1049	20.1.3$$QI ^XUSNPI(): Get Provi der Entiti es256
	1050	20.1.3.1Ex amples256
	1051	20.1.4$$TA XIND^XUSTA X(): Get T axonomy Co de from Fi le #200257
	1052	20.1.4.1Ex ample257
	1053	20.1.5$$TA XORG^XUSTA X(): Get T axonomy Co de from Fi le #4258
	1054	20.1.5.1Ex ample258
	1055	21Operatin g System ( OS) Interf ace: Devel oper Tools 259
	1056	21.1Overvi ew259
	1057	21.2Direct Mode Util ities259
	1058	21.2.1>D ^ %ZTBKC: Gl obal Block Count259
	1059	21.2.2>D ^ ZTMGRSET: Update ^%Z OSF Nodes2 59
	1060	21.3Applic ation Prog ramming In terface (A PI)259
	1061	21.3.1^%ZO SF(): Oper ating Syst em-depende nt Logic G lobal259
	1062	21.3.2$$AC TJ^%ZOSV: Number of Active Job s262
	1063	21.3.3$$AV J^%ZOSV: N umber of A vailable J obs263
	1064	21.3.4DOLR O^%ZOSV: D isplay Loc al Variabl es263
	1065	21.3.4.1Ex ample263
	1066	21.3.5GETE NV^%ZOSV: Current Sy stem Infor mation264
	1067	21.3.6$$LG R^%ZOSV: L ast Global Reference 264
	1068	21.3.6.1Ex ample264
	1069	21.3.7LOGR SRC^%ZOSV( ): Record Resource U sage (RUM) 264
	1070	21.3.8$$OS ^%ZOSV: Ge t Operatin g System I nformation 265
	1071	21.3.8.1Ex ample265
	1072	21.3.9SETE NV^%ZOSV: Set VMS Pr ocess Name (Caché/Op enVMS Syst ems)265
	1073	21.3.10SET NM^%ZOSV() : Set VMS Process Na me (Caché/ OpenVMS Sy stems)266
	1074	21.3.11T0^ %ZOSV: Sta rt RT Meas ure (Obsol ete)266
	1075	21.3.12T1^ %ZOSV: Sto p RT Measu re (Obsole te)267
	1076	21.3.13$$V ERSION^%ZO SV(): Get OS Version Number or Name268
	1077	21.3.13.1E xamples268
	1078	22Security Keys: Dev eloper Too ls269
	1079	22.1Overvi ew269
	1080	22.2Key Lo okup269
	1081	22.3Person Lookup269
	1082	22.4Applic ation Prog ramming In terface (A PI)269
	1083	22.4.1DEL^ XPDKEY(): Delete Sec urity Key2 69
	1084	22.4.1.1Ex ample269
	1085	22.4.2$$LK UP^XPDKEY( ): Look Up Security Key Value2 70
	1086	22.4.2.1Ex ample270
	1087	22.4.3$$RE NAME^XPDKE Y(): Renam e Security Key270
	1088	22.4.4OWNS KEY^XUSRB( ): Verify Security K eys Assign ed to a Us er271
	1089	22.4.4.1Ex amples271
	1090	23Server O ptions: De veloper To ols273
	1091	23.1Tools for Proces sing Serve r Requests 273
	1092	23.2Key Va riables Wh en a Serve r Option i s Running2 73
	1093	23.3Append ing Text t o a Server Request B ulletin or Mailman R eply274
	1094	23.4Custom izing a Se rver Reque st Bulleti n274
	1095	24Signon/S ecurity: D eveloper T ools276
	1096	24.1Overvi ew276
	1097	24.2Direct Mode Util ities276
	1098	24.2.1^XUP : Programm er Signon2 76
	1099	24.2.2^XUS : User Sig non: No Er ror Trappi ng276
	1100	24.2.3H^XU S: Program mer Halt27 7
	1101	24.2.4^XUS CLEAN: Pro grammer Ha lt277
	1102	24.2.5^ZU: User Sign on277
	1103	24.3XU USE R SIGN-ON Option277
	1104	24.3.1XU U SER SIGN-O N: Package -specific Signon Act ions277
	1105	24.3.1.1Ex ample278
	1106	24.4XU USE R START-UP Option278
	1107	24.4.1XU U SER START- UP: Applic ation-spec ific Signo n Actions2 78
	1108	24.4.1.1Ex ample:279
	1109	24.5XU USE R TERMINAT E Option27 9
	1110	24.5.1Disc ontinuatio n of USER TERMINATE ROUTINE279
	1111	24.5.2Crea ting a Pac kage-speci fic User T ermination Action279
	1112	24.6Applic ation Prog ramming In terface (A PI)280
	1113	24.6.1$$GE T^XUPARAM( ): Get Par ameters280
	1114	24.6.2$$KS P^XUPARAM( ): Return Kernel Sit e Paramete r281
	1115	24.6.2.1Ex amples281
	1116	24.6.3$$LK UP^XUPARAM (): Look U p Paramete rs282
	1117	24.6.4SET^ XUPARAM(): Set Param eters282
	1118	24.6.5$$PR OD^XUPROD( ): Product ion Vs. Te st Account 283
	1119	24.6.6H^XU S: Program mer Halt28 3
	1120	24.6.7SET^ XUS1A(): O utput Mess age During Signon284
	1121	24.6.7.1De tails284
	1122	24.6.8AVHL PTXT^XUS2: Get Help Text284
	1123	24.6.9$$CR EATE^XUSAP : Create A pplication Proxy Use r285
	1124	24.6.9.1Ex amples287
	1125	24.6.10KIL L^XUSCLEAN : Clear al l but Kern el Variabl es289
	1126	24.6.11$$A DD^XUSERNE W(): Add N ew Users29 0
	1127	24.6.11.1E xamples291
	1128	24.6.12$$C HECKAV^XUS RB(): Chec k Access/V erify Code s291
	1129	24.6.12.1E xample292
	1130	24.6.13CVC ^XUSRB: Vi stALink—Ch ange User’ s Verify C ode292
	1131	24.6.14$$I NHIBIT^XUS RB: Check if Logons Inhibited2 92
	1132	24.6.15INT RO^XUSRB: VistALink— Get Introd uctory Tex t293
	1133	24.6.16LOG OUT^XUSRB: VistALink —Log Out U ser from M 293
	1134	24.6.17SET UP^XUSR B( ): VistALi nk—Set Up User’s Par tition in M293
	1135	24.6.18VAL IDAV^XUSRB (): VistAL ink—Valida te User Cr edentials2 94
	1136	24.6.19$$D ECRYP^XUSR B1(): Decr ypt String 294
	1137	24.6.20$$E NCRYP^XUSR B1(): Encr ypt String 295
	1138	24.6.21$$H ANDLE^XUSR B4(): Retu rn Unique Session ID String295
	1139	24.6.21.1E xample296
	1140	24.6.22^XU VERIFY: Ve rify Acces s and Veri fy Codes29 6
	1141	24.6.23$$C HECKAV^XUV ERIFY(): C heck Acces s/Verify C odes297
	1142	24.6.23.1E xample297
	1143	24.6.24WIT NESS^XUVER IFY(): Ret urn IEN of Users wit h A/V Code s & Securi ty Keys297
	1144	24.6.24.1E xample298
	1145	24.6.25GET PEER^%ZOSV : VistALin k—Get IP A ddress for Current S ession298
	1146	25Spooling : Develope r Tools299
	1147	25.1Overvi ew299
	1148	25.2Applic ation Prog ramming In terface (A PI)300
	1149	25.2.1DSD^ ZISPL: Del ete Spool Data File Entry300
	1150	25.2.2DSDO C^ZISPL: D elete Spoo l Document File Entr y300
	1151	26TaskMan: Developer Tools301
	1152	26.1Overvi ew301
	1153	26.2How to Write Cod e to Queue Tasks301
	1154	26.2.1Queu ers301
	1155	26.2.1.1Ca lling EN^X UTMDEVQ to Create Ta sks302
	1156	26.2.1.2Cr eating Tas ks Using S cheduled O ptions302
	1157	26.2.2Task s303
	1158	26.2.2.1Ke y Variable s and Envi ronment Wh en Task is Running30 3
	1159	26.2.2.2Ch ecking for Stop Requ ests304
	1160	26.2.2.3Pu rging the Task Recor d305
	1161	26.2.2.4Ch ecking For Backgroun d Executio n: ZTQUEUE D306
	1162	26.2.2.5Po st-Executi on Command s: ZTREQ30 6
	1163	26.2.2.6Ca lling ^%ZT LOAD withi n a Task30 7
	1164	26.2.2.7Ca lling the Device Han dler (^%ZI S) within a Task307
	1165	26.2.2.8Lo ng Running Tasks—Wri ting Two-s tep Tasks3 07
	1166	26.2.2.9Lo ng Running Tasks—Usi ng ^%ZIS30 8
	1167	26.2.2.10U sing SYNC FLAGs to C ontrol Seq uences of Tasks310
	1168	26.3Direct Mode Util ities311
	1169	26.3.1>D ^ ZTMB: Star t TaskMan3 11
	1170	26.3.2>D R ESTART^ZTM B: Restart TaskMan31 1
	1171	26.3.3>D ^ ZTMCHK: Ch eck TaskMa n’s Enviro nment311
	1172	26.3.4>D R UN^ZTMKU: Remove Tas kman from WAIT State Option311
	1173	26.3.5>D S TOP^ZTMKU: Stop Task Manager O ption311
	1174	26.3.6>D W AIT^ZTMKU: Place Tas kman in a WAIT State Option311
	1175	26.3.7>D ^ ZTMON: Mon itor TaskM an Option3 11
	1176	26.4Applic ation Prog ramming In terface (A PI)312
	1177	26.4.1TOUC H^XUSCLEAN : Notify K ernel of T asks that Run 7 Days or Longer 312
	1178	26.4.2$$DE V^XUTMDEVQ (): Force Queuing—As k for Devi ce312
	1179	26.4.2.1Ex ample314
	1180	26.4.3EN^X UTMDEVQ(): Run a Tas k (Directl y or Queue d)314
	1181	26.4.3.1Ex ample316
	1182	26.4.4$$NO DEV^XUTMDE VQ(): Forc e Queuing— No Device Selection3 16
	1183	26.4.4.1Ex ample317
	1184	26.4.5$$QQ ^XUTMDEVQ( ): Double Queue—Dire ct Queuing in a Sing le Call318
	1185	26.4.5.1Ex ample320
	1186	26.4.6$$RE QQ^XUTMDEV Q(): Sched ule Second Part of a Task321
	1187	26.4.6.1Ex ample322
	1188	26.4.7DISP ^XUTMOPT() : Display Option Sch edule322
	1189	26.4.7.1Ex ample323
	1190	26.4.8EDIT ^XUTMOPT() : Edit an Option’s S cheduling3 23
	1191	26.4.9OPTS TAT^XUTMOP T(): Obtai n Option S chedule323
	1192	26.4.9.1Ex ample323
	1193	26.4.10RES CH^XUTMOPT (): Set Up Option Sc hedule324
	1194	26.4.11EN^ XUTMTP(): Display HL 7 Task Inf ormation32 4
	1195	26.4.12^%Z TLOAD: Que ue a Task3 25
	1196	26.4.12.1I nteractive Use of ^% ZTLOAD328
	1197	26.4.12.2N on-interac tive Use o f ^%ZTLOAD 329
	1198	26.4.12.3Q ueuing Tas ks without an I/O De vice329
	1199	26.4.12.4E xample330
	1200	26.4.12.5C ode Execut ion332
	1201	26.4.12.6O utput332
	1202	26.4.13$$A SKSTOP^%ZT LOAD: Stop TaskMan T ask333
	1203	26.4.14DES C^%ZTLOAD( ): Find Ta sks with a Descripti on333
	1204	26.4.15DQ^ %ZTLOAD: U nschedule a Task334
	1205	26.4.16ISQ ED^%ZTLOAD : Return T ask Status 334
	1206	26.4.17$$J OB^%ZTLOAD (): Return a Job Num ber for a Task336
	1207	26.4.18KIL L^%ZTLOAD: Delete a Task336
	1208	26.4.19OPT ION^%ZTLOA D(): Find Tasks for an Option3 37
	1209	26.4.20PCL EAR^%ZTLOA D(): Clear Persisten t Flag for a Task337
	1210	26.4.21$$P SET^%ZTLOA D(): Set T ask as Per sistent337
	1211	26.4.22REQ ^%ZTLOAD: Requeue a Task338
	1212	26.4.22.1E xample340
	1213	26.4.22.2C ode Execut ion342
	1214	26.4.22.3O utput342
	1215	26.4.23RTN ^%ZTLOAD() : Find Tas ks that Ca ll a Routi ne342
	1216	26.4.24$$S ^%ZTLOAD() : Check fo r Task Sto p Request3 43
	1217	26.4.25STA T^%ZTLOAD: Task Stat us343
	1218	26.4.26$$T M^%ZTLOAD: Check if TaskMan is Running34 5
	1219	26.4.27ZTS AVE^%ZTLOA D(): Build ZTSAVE Ar ray345
	1220	27Toolkit: Developer Tools346
	1221	27.1Toolki t—Data Sta ndardizati on346
	1222	27.1.1Over view346
	1223	27.1.2Repl acement Re lationship s347
	1224	27.1.3Appl ication Pr ogramming Interfaces (APIs)348
	1225	27.1.4$$GE TRPLC^XTID TRM(): Get Mapped Te rms (Term/ Concept)34 8
	1226	27.1.4.1Ex ample349
	1227	27.1.5$$RP LCLST^XTID TRM(): Get Replaceme nt Terms, w/Optional Status Da te & Histo ry (Term/C oncept)349
	1228	27.1.5.1Ex ample350
	1229	27.1.6$$RP LCMNT^XTID TRM(): M O ne Term to Another ( Term/Conce pt)350
	1230	27.1.6.1Ex ample351
	1231	27.1.7$$RP LCTRL^XTID TRM(): Get Replaceme nt Trail, w/ Replace d “BY” & R eplacement “FOR” Ter ms351
	1232	27.1.7.1Ex ample352
	1233	27.1.8$$RP LCVALS^XTI DTRM(): Ge t Field Va lues of Fi nal Replac ement Term (Term/Con cept)352
	1234	27.1.8.1Ex ample353
	1235	27.1.9$$SE TRPLC^XTID TRM(): Set Replaceme nt Terms ( Term/Conce pt)353
	1236	27.1.9.1Ex ample354
	1237	27.2Toolki t—Duplicat e Record M erge355
	1238	27.2.1Over view355
	1239	27.2.1.1Ma nner in wh ich data i s Merged35 5
	1240	27.3Develo ping a Fil e Merge Ca pability35 6
	1241	27.3.1Step 1356
	1242	27.3.2Step 2356
	1243	27.3.3Desc ription of What Occu rs during the Merge3 57
	1244	27.3.4Entr ies Needed in the PA CKAGE File (#9.4)358
	1245	27.3.5Step 3358
	1246	27.3.5.1Ex planation of Fields in Logical Order of Entry359
	1247	27.3.6Spec ial Proces sing Routi ne Example s364
	1248	27.3.6.1Ca ndidate Co llection R outine for Patient M erge Examp le364
	1249	27.3.6.2Du plicate Te st Routine Examples3 66
	1250	27.3.7Appl ication Pr ogramming Interfaces (APIs)368
	1251	27.3.8EN^X DRMERG(): Merge File Entries36 8
	1252	27.3.8.1Ex amples368
	1253	27.3.8.2Pr oblems Rel ated To Da ta Entry W hile Mergi ng369
	1254	27.3.9REST ART^XDRMER G(): Resta rt Merge37 0
	1255	27.3.10SAV EMERG^XDRM ERGB(): Sa ve Image o f Existing and Merge d Data371
	1256	27.4Toolki t—HTTP Cli ent371
	1257	27.4.1Over view371
	1258	27.4.2Appl ication Pr ogramming Interfaces (APIs)372
	1259	27.4.3$$GE TURL^XTHC1 0: Return URL Data U sing HTTP3 72
	1260	27.4.4$$EN CODE^XTHCU RL: Encode s a Query String374
	1261	27.4.4.1Ex ample375
	1262	27.4.5$$MA KEURL^XTHC URL: Creat es a URL f rom Compon ents375
	1263	27.4.5.1Ex ample376
	1264	27.4.6$$PA RSEURL^XTH CURL: Pars es a URL37 6
	1265	27.4.6.1Ex ample377
	1266	27.4.7$$DE CODE^XTHCU TL: Decode s a String 377
	1267	27.4.7.1Ex ample377
	1268	27.5Toolki t—KERMIT A PIs378
	1269	27.5.1RFIL E^XTKERM4: Add Entri es to Kerm it Holding File378
	1270	27.5.2RECE IVE^XTKERM IT: Load a File into the Host3 78
	1271	27.5.3SEND ^XTKERMIT: Send Data from Host 379
	1272	27.6Toolki t—Multi-Te rm Look-Up (MTLU) AP Is381
	1273	27.6.1How to Overrid e381
	1274	27.6.2Appl ication Pr ogramming Interfaces (APIs)381
	1275	27.6.2.1MT LU and VA FileMan Su pported Ca lls381
	1276	27.6.2.2Ke rnel Toolk it Enhance d APIs382
	1277	27.6.3XTLK KWL^XTLKKW L: Perform Supported VA FileMa n Calls on Files Con figured fo r MTLU382
	1278	27.6.4DK^X TLKMGR(): Delete Key words from the Local Keyword F ile383
	1279	27.6.5DLL^ XTLKMGR(): Delete an Entry fro m the Loca l Lookup F ile383
	1280	27.6.6DSH^ XTLKMGR(): Delete Sh ortcuts fr om the Loc al Shortcu t File384
	1281	27.6.7DSY^ XTLKMGR(): Delete Sy nonyms fro m the Loca l Synonym File384
	1282	27.6.8K^XT LKMGR(): A dd Keyword s to the L ocal Keywo rd File385
	1283	27.6.9L^XT LKMGR(): D efine a Fi le in the Local Look up File385
	1284	27.6.10LKU P^XTLKMGR( ): General Lookup Fa cility for MTLU386
	1285	27.6.10.1E xamples387
	1286	27.6.11SH^ XTLKMGR(): Add Short cuts to th e Local Sh ortcut Fil e390
	1287	27.6.12SY^ XTLKMGR(): Add Terms and Synon yms to the Local Syn onym File3 91
	1288	27.7Toolki t—M Unit U tility392
	1289	27.7.1Over view392
	1290	27.7.2Intr oduction t o M Unit T esting392
	1291	27.7.3M Un it Test De finitions3 93
	1292	27.7.4Gett ing Starte d393
	1293	27.7.5Appl ication Pr ogramming Interfaces (APIs)393
	1294	27.7.6EN^X TMUNIT(): Run Unit T ests393
	1295	27.7.6.1ST ARTUP394
	1296	27.7.6.2SH UTDOWN394
	1297	27.7.6.3SE TUP394
	1298	27.7.6.4TE ARDOWN395
	1299	27.7.6.5XT ENT: List Unit Test Entry Poin ts395
	1300	27.7.6.6XT ROU: List of Routine s Containi ng Additio nal Tests3 95
	1301	27.7.7CHKE Q^XTMUNIT: Check Two Values fo r Equivale nce395
	1302	27.7.8CHKL EAKS^XTMUN IT(): Chec k for Vari able Leaks 396
	1303	27.7.9CHKT F^XTMUNIT( ): Test Co nditional Values397
	1304	27.7.10FAI L^XTMUNIT( ): Generat e an Error Message39 7
	1305	27.7.11$$I SUTEST^XTM UNIT: Eval uate if Un it Test is Running39 7
	1306	27.7.12SUC CEED^XTMUN IT: Increm ent Test C ounter398
	1307	27.7.13Sam ple M Unit Utility O utput399
	1308	27.8Toolki t—Paramete r Tools400
	1309	27.8.1Over view400
	1310	27.8.2Defi nitions400
	1311	27.8.2.1En tity400
	1312	27.8.2.2Pa rameter401
	1313	27.8.2.3Va lue401
	1314	27.8.2.4In stance401
	1315	27.8.2.5Pa rameter Te mplate401
	1316	27.8.3Appl ication Pr ogramming Interfaces (APIs)401
	1317	27.8.4ADD^ XPAR(): Ad d Paramete r Value401
	1318	27.8.4.1Ex ample:401
	1319	27.8.5CHG^ XPAR(): Ch ange Param eter Value 402
	1320	27.8.5.1Ex ample402
	1321	27.8.6DEL^ XPAR(): De lete Param eter Value 402
	1322	27.8.6.1Ex ample402
	1323	27.8.7EN^X PAR(): Add , Change, Delete Par ameters403
	1324	27.8.7.1Ex ample404
	1325	27.8.8ENVA L^XPAR(): Return All Parameter Instances 404
	1326	27.8.9$$GE T^XPAR(): Return an Instance o f a Parame ter405
	1327	27.8.10GET LST^XPAR() : Return A ll Instanc es of a Pa rameter406
	1328	27.8.10.1E xample:407
	1329	27.8.11GET WP^XPAR(): Return Wo rd-process ing Text40 7
	1330	27.8.11.1E xample:408
	1331	27.8.12NDE L^XPAR(): Delete All Instances of a Para meter408
	1332	27.8.12.1E xample408
	1333	27.8.13PUT ^XPAR(): A dd/Update Parameter Instance40 9
	1334	27.8.13.1E xample:409
	1335	27.8.14REP ^XPAR(): R eplace Ins tance Valu e409
	1336	27.8.15BLD LST^XPARED IT(): Retu rn All Ent ities of a Parameter 410
	1337	27.8.16EDI T^XPAREDIT (): Edit I nstance an d Value of a Paramet er410
	1338	27.8.17EDI TPAR^XPARE DIT(): Edi t Single P arameter41 0
	1339	27.8.18EN^ XPAREDIT: Parameter Edit Promp t411
	1340	27.8.19GET ENT^XPARED IT(): Prom pt for Ent ity Based on Paramet er411
	1341	27.8.20GET PAR^XPARED IT(): Sele ct Paramet er Definit ion File41 2
	1342	27.8.21TED ^XPAREDIT( ): Edit Te mplate Par ameters (N o Dash Div iders)412
	1343	27.8.22TED H^XPAREDIT (): Edit T emplate Pa rameters ( with Dash Dividers)4 13
	1344	27.9Toolki t—VHA Uniq ue ID (VUI D) APIs414
	1345	27.9.1GETI REF^XTID() : Get IREF (Term/Con cept)414
	1346	27.9.1.1Ex amples415
	1347	27.9.2$$GE TMASTR^XTI D(): Get M aster VUID Flag (Ter m/Concept) 416
	1348	27.9.2.1Ex amples417
	1349	27.9.3$$GE TSTAT^XTID (): Get St atus Infor mation (Te rm/Concept )417
	1350	27.9.3.1Ex amples418
	1351	27.9.4$$GE TVUID^XTID (): Get VU ID (Term/C oncept)419
	1352	27.9.4.1Ex amples420
	1353	27.9.5$$SC REEN^XTID( ): Get Scr eening Con dition (Te rm/Concept )420
	1354	27.9.5.1Ex amples421
	1355	27.9.6$$SE TMASTR^XTI D(): Set M aster VUID Flag (Ter m/Concept) 422
	1356	27.9.6.1Ex amples423
	1357	27.9.7$$SE TSTAT^XTID (): Set St atus Infor mation (Te rm/Concept )423
	1358	27.9.7.1Ex amples424
	1359	27.9.8$$SE TVUID^XTID (): Set VU ID (Term/C oncept)425
	1360	27.9.8.1Ex amples426
	1361	27.10Toolk it—Routine Tools427
	1362	27.10.1Dir ect Mode U tilities42 7
	1363	27.10.2Rou tine Tools Menu428
	1364	27.10.2.1A nalyzing R outines429
	1365	27.10.2.2E diting Rou tines431
	1366	27.10.2.3P rinting Ro utines432
	1367	27.10.2.4C omparing R outines433
	1368	27.10.2.5D eleting Ro utines434
	1369	27.10.2.6L oad and Sa ve Routine s434
	1370	27.11Toolk it—Verific ation Tool s435
	1371	27.11.1Dir ect Mode U tilities43 5
	1372	27.11.2Ver ifier Tool s Menu436
	1373	27.11.2.1U pdate with Current R outines Op tion436
	1374	27.11.2.2R outine Com pare - Cur rent with Previous O ption437
	1375	27.11.3Pro grammer Op tions Menu 437
	1376	27.11.3.1C alculate a nd Show Ch ecksum Val ues Option 437
	1377	27.11.3.2E rror Proce ssing—Kern el Error T rapping an d Reportin g438
	1378	27.12XINDE X439
	1379	27.12.1Typ es of XIND EX Finding s441
	1380	27.12.2Run ning the X INDEX Util ity444
	1381	27.12.3Ana lysis of X INDEX Erro r Findings by Catego ry450
	1382	27.12.3.1F atal M Err ors (Hard MUMPS Erro r)450
	1383	27.12.3.2W arning Vio lation Err ors (Accor ding to VA Conventio ns)453
	1384	27.12.3.3S tandards V iolation E rrors (Acc ording to VA Standar ds)454
	1385	27.12.3.4I nformation al Errors4 59
	1386	27.12.3.5M arked Item s Errors ( Manual Che ck)460
	1387	28Unwinder : Develope r Tools461
	1388	28.1Applic ation Prog ramming In terface (A PI)461
	1389	28.1.1EN^X QOR(): Nav igating Pr otocols461
	1390	28.1.2EN1^ XQOR(): Na vigating P rotocols46 1
	1391	28.1.3MSG^ XQOR(): En able HL7 M essaging46 2
	1392	28.1.4EN^X QORM(): Me nu Item Di splay and Selection4 62
	1393	28.1.5XREF ^XQORM(): Force Menu Recompile 463
	1394	28.1.6DISP ^XQORM1(): Display M enu Select ions From Help Code4 63
	1395	29User: De veloper To ols464
	1396	29.1Applic ation Prog ramming In terface (A PI)464
	1397	29.1.1$$CO DE2TXT^XUA 4A72(): Ge t HCFA Tex t464
	1398	29.1.2$$GE T^XUA4A72( ): Get Spe cialty and Subspecia lty for a User464
	1399	29.1.3$$IE N2CODE^XUA 4A72(): Ge t VA Code4 65
	1400	29.1.4$$DT IME^XUP(): Reset DTI ME for USE R465
	1401	29.1.4.1Ex amples466
	1402	29.1.5$$AC TIVE^XUSER (): Status Indicator 467
	1403	29.1.5.1Ex amples468
	1404	29.1.6$$DE A^XUSER()— Get User’s DEA Numbe r468
	1405	29.1.6.1Ex amples469
	1406	29.1.7$$DE TOX^XUSER( )—Get Deto x/Maintena nce ID Num ber471
	1407	29.1.8DIV4 ^XUSE R(): Get User Divisions4 72
	1408	29.1.8.1Ex ample472
	1409	29.1.9$$LO OKUP^XUSER (): New Pe rson File Lookup473
	1410	29.1.9.1Ex amples474
	1411	29.1.10$$N AME^XUSER( ): Get Nam e of User4 75
	1412	29.1.10.1E xamples475
	1413	29.1.11$$P ROVIDER^XU SER(): Pro viders in New Person File476
	1414	29.1.11.1E xamples476
	1415	29.1.12$$S DEA^XUSER( )—Check fo r Prescrib ing Privil eges477
	1416	29.1.13$$V DEA^XUSER( )—Check if User Can Sign Contr olled Subs tance Orde rs479
	1417	29.1.14$$K CHK^XUSRB( ): Check I f User Hol ds Securit y Key480
	1418	29.1.14.1E xamples480
	1419	29.1.15DIV GET^XUSRB2 (): Get Di visions fo r Current User481
	1420	29.1.16DIV SET^XUSRB2 (): Set Di vision for Current U ser481
	1421	29.1.17USE RINFO^XUSR B2(): Get Demographi cs for Cur rent User4 82
	1422	30XGF Func tion Libra ry: Develo per Tools4 83
	1423	30.1Overvi ew483
	1424	30.2Direct Mode Util ities484
	1425	30.2.1^XGF DEMO: Demo Program48 4
	1426	30.3Applic ation Prog ramming In terface (A PI)485
	1427	30.3.1CHGA ^XGF(): Sc reen Chang e Attribut es485
	1428	30.3.1.1Ex amples486
	1429	30.3.2CLEA N^XGF: Scr een/Keyboa rd Exit an d Cleanup4 86
	1430	30.3.3CLEA R^XGF(): S creen Clea r Region48 7
	1431	30.3.3.1Ex amples487
	1432	30.3.4FRAM E^XGF(): S creen Fram e488
	1433	30.3.4.1Ex ample488
	1434	30.3.5INIT KB^XGF(): Keyboard S etup Only4 89
	1435	30.3.6IOXY ^XGF(): Sc reen Curso r Placemen t489
	1436	30.3.6.1Ex ample490
	1437	30.3.7PREP ^XGF(): Sc reen/Keybo ard Setup4 90
	1438	30.3.8$$RE AD^XGF(): Read Using Escape Pr ocessing49 1
	1439	30.3.8.1Ex amples492
	1440	30.3.9RESE TKB^XGF: E xit XGF Ke yboard493
	1441	30.3.10RES TORE^XGF() : Screen R estore493
	1442	30.3.10.1E xample494
	1443	30.3.11SAV E^XGF(): S creen Save 494
	1444	30.3.11.1E xample494
	1445	30.3.12SAY ^XGF(): Sc reen Strin g495
	1446	30.3.12.1E xamples496
	1447	30.3.13SAY U^XGF(): S creen Stri ng with At tributes49 6
	1448	30.3.13.1E xample497
	1449	30.3.14SET A^XGF(): S creen Vide o Attribut es497
	1450	30.3.14.1E xample498
	1451	30.3.15WIN ^XGF(): Sc reen Text Window498
	1452	30.3.15.1E xamples499
	1453	31XLF Func tion Libra ry: Develo per Tools5 00
	1454	31.1Overvi ew500
	1455	31.2Applic ation Prog ramming In terface (A PI)500
	1456	31.3CRC Fu nctions—XL FCRC500
	1457	31.3.1$$CR C16^XLFCRC (): Cyclic Redundanc y Code 165 00
	1458	31.3.1.1Ex amples501
	1459	31.3.2$$CR C32^XLFCRC (): Cyclic Redundanc y Code 325 02
	1460	31.3.2.1Ex amples502
	1461	31.4Date F unctions—X LFDT503
	1462	31.4.1$$%H ^XLFDT(): Convert Se conds to $ H503
	1463	31.4.1.1Ex ample503
	1464	31.4.2$$DO W^XLFDT(): Day of We ek503
	1465	31.4.2.1Ex amples504
	1466	31.4.3$$DT ^XLFDT: Cu rrent Date (VA FileM an Date Fo rmat)504
	1467	31.4.3.1Ex ample504
	1468	31.4.4$$FM ADD^XLFDT( ): VA File Man Date A dd505
	1469	31.4.4.1Ex ample505
	1470	31.4.5$$FM DIFF^XLFDT (): VA Fil eMan Date Difference 505
	1471	31.4.5.1Ex amples506
	1472	31.4.6$$FM TE^XLFDT() : Convert VA FileMan Date to E xternal Fo rmat506
	1473	31.4.6.1Ex amples507
	1474	31.4.7$$FM TH^XLFDT() : Convert VA FileMan Date to $ H511
	1475	31.4.7.1Ex amples511
	1476	31.4.8$$FM THL7^XLFDT (): Conver t VA FileM an Date to HL7 Date5 11
	1477	31.4.8.1Ex ample512
	1478	31.4.9$$HA DD^XLFDT() : $H Add51 2
	1479	31.4.9.1Ex ample512
	1480	31.4.10$$H DIFF^XLFDT (): $H Dif ference512
	1481	31.4.10.1E xamples513
	1482	31.4.11$$H L7TFM^XLFD T(): Conve rt HL7 Dat e to VA Fi leMan Date 513
	1483	31.4.11.1E xamples514
	1484	31.4.12$$H TE^XLFDT() : Convert $H to Exte rnal Forma t515
	1485	31.4.12.1E xamples516
	1486	31.4.13$$H TFM^XLFDT( ): Convert $H to VA FileMan Da te Format5 17
	1487	31.4.13.1E xamples517
	1488	31.4.14$$N OW^XLFDT: Current Da te and Tim e (VA File Man Format )517
	1489	31.4.14.1E xample518
	1490	31.4.15$$S CH^XLFDT() : Next Sch eduled Run time518
	1491	31.4.15.1E xamples520
	1492	31.4.16$$S EC^XLFDT() : Convert $H/VA File Man date t o Seconds5 21
	1493	31.4.16.1E xamples521
	1494	31.4.17$$T Z^XLFDT: T ime Zone O ffset (GMT )522
	1495	31.4.17.1E xample522
	1496	31.4.18$$W ITHIN^XLFD T(): Check s Dates/Ti mes within Schedule5 22
	1497	31.5Hyperb olic Trigo nometric F unctions—X LFHYPER523
	1498	31.5.1$$AC OSH^XLFHYP ER(): Hype rbolic Arc -cosine523
	1499	31.5.1.1Ex ample523
	1500	31.5.2$$AC OTH^XLFHYP ER(): Hype rbolic Arc -cotangent 524
	1501	31.5.2.1Ex ample524
	1502	31.5.3$$AC SCH^XLFHYP ER(): Hype rbolic Arc -cosecant5 24
	1503	31.5.3.1Ex ample524
	1504	31.5.4$$AS ECH^XLFHYP ER(): Hype rbolic Arc -secant525
	1505	31.5.4.1Ex ample525
	1506	31.5.5$$AS INH^XLFHYP ER(): Hype rbolic Arc -sine525
	1507	31.5.5.1Ex ample525
	1508	31.5.6$$AT ANH^XLFHYP ER(): Hype rbolic Arc -tangent52 6
	1509	31.5.6.1Ex ample526
	1510	31.5.7$$CO SH ^XLFHYP ER(): Hype rbolic Cos ine526
	1511	31.5.7.1Ex ample526
	1512	31.5.8$$CO TH^XLFHYPE R(): Hyper bolic Cota ngent527
	1513	31.5.8.1Ex ample527
	1514	31.5.9$$CS CH^XLFHYPE R(): Hyper bolic Cose cant527
	1515	31.5.9.1Ex ample527
	1516	31.5.10$$S ECH^XLFHYP ER(): Hype rbolic Sec ant528
	1517	31.5.10.1E xample528
	1518	31.5.11$$S INH^XLFHYP ER(): Hype rbolic Sin e528
	1519	31.5.11.1E xamples528
	1520	31.5.12$$T ANH^XLFHYP ER(): Hype rbolic Tan gent529
	1521	31.5.12.1E xample529
	1522	31.6Mathem atical Fun ctions—XLF MTH529
	1523	31.6.1$$AB S^XLFMTH() : Absolute Value529
	1524	31.6.1.1Ex ample530
	1525	31.6.2$$AC OS^XLFMTH( ): Arc-cos ine (Radia ns)530
	1526	31.6.2.1Ex ample530
	1527	31.6.3$$AC OSDEG^XLFM TH(): Arc- cosine (De grees)530
	1528	31.6.3.1Ex ample531
	1529	31.6.4$$AC OT^XLFMTH( ): Arc-cot angent (Ra dians)531
	1530	31.6.4.1Ex ample531
	1531	31.6.5$$AC OTDEG^XLFM TH(): Arc- cotangent (Degrees)5 31
	1532	31.6.5.1Ex ample532
	1533	31.6.6$$AC SC^XLFMTH( ): Arc-cos ecant (Rad ians)532
	1534	31.6.6.1Ex ample532
	1535	31.6.7$$AC SCDEG^XLFM TH(): Arc- cosecant ( Degrees)53 2
	1536	31.6.7.1Ex ample533
	1537	31.6.8$$AS EC^XLFMTH( ): Arc-sec ant (Radia ns)533
	1538	31.6.8.1Ex ample533
	1539	31.6.9$$AS ECDEG^XLFM TH(): Arc- secant (De grees)533
	1540	31.6.9.1Ex ample534
	1541	31.6.10$$A SIN^XLFMTH (): Arc-si ne (Radian s)534
	1542	31.6.10.1E xample534
	1543	31.6.11$$A SINDEG^XLF MTH(): Arc -sine (Deg rees)534
	1544	31.6.11.1E xample535
	1545	31.6.12$$A TAN^XLFMTH (): Arc-ta ngent (Rad ians)535
	1546	31.6.12.1E xample535
	1547	31.6.13$$A TANDEG^XLF MTH(): Arc -tangent ( Degrees)53 5
	1548	31.6.13.1E xample536
	1549	31.6.14$$C OS^XLFMTH( ): Cosine (Radians)5 36
	1550	31.6.14.1E xample536
	1551	31.6.15$$C OSDEG^XLFM TH(): Cosi ne (Degree s)536
	1552	31.6.15.1E xample537
	1553	31.6.16$$C OT^XLFMTH( ): Cotange nt (Radian s)537
	1554	31.6.16.1E xample537
	1555	31.6.17$$C OTDEG^XLFM TH(): Cota ngent (Deg rees)537
	1556	31.6.17.1E xample538
	1557	31.6.18$$C SC^XLFMTH( ): Cosecan t (Radians )538
	1558	31.6.18.1E xample538
	1559	31.6.19$$C SCDEG^XLFM TH(): Cose cant (Degr ees)538
	1560	31.6.19.1E xample539
	1561	31.6.20$$D ECDMS^XLFM TH(): Conv ert Decima ls to Degr ees:Minute s:Seconds5 39
	1562	31.6.20.1E xample539
	1563	31.6.21$$D MSDEC^XLFM TH(): Conv ert Degree s:Minutes: Seconds to Decimal53 9
	1564	31.6.21.1E xample540
	1565	31.6.22$$D TR^XLFMTH( ): Convert Degrees t o Radians5 40
	1566	31.6.22.1E xample540
	1567	31.6.23$$E ^XLFMTH(): e—Natural Logarithm 540
	1568	31.6.23.1E xample541
	1569	31.6.24$$E XP^XLFMTH( ): e—Natur al Logarit hm to the Nth Power5 41
	1570	31.6.24.1E xample541
	1571	31.6.25$$L N^XLFMTH() : Natural Log (Base e)541
	1572	31.6.25.1E xample542
	1573	31.6.26$$L OG^XLFMTH( ): Logarit hm (Base 1 0)542
	1574	31.6.26.1E xample542
	1575	31.6.27$$M AX^XLFMTH( ): Maximum of Two Nu mbers542
	1576	31.6.27.1E xample543
	1577	31.6.28$$M IN^XLFMTH( ): Minimum of Two Nu mbers543
	1578	31.6.28.1E xample543
	1579	31.6.29$$P I^XLFMTH() : PI543
	1580	31.6.29.1E xample544
	1581	31.6.30$$P WR^XLFMTH( ): X to th e Y Power5 44
	1582	31.6.30.1E xample544
	1583	31.6.31$$R TD^XLFMTH( ): Convert Radians t o Degrees5 44
	1584	31.6.31.1E xample545
	1585	31.6.32$$S D^XLFMTH() : Standard Deviation 545
	1586	31.6.32.1E xample545
	1587	31.6.33$$S EC^XLFMTH( ): Secant (Radians)5 45
	1588	31.6.33.1E xample546
	1589	31.6.34$$S ECDEG^XLFM TH(): Seca nt (Degree s)546
	1590	31.6.34.1E xample546
	1591	31.6.35$$S IN^XLFMTH( ): Sine (R adians)546
	1592	31.6.35.1E xample547
	1593	31.6.36$$S INDEG^XLFM TH(): Sine (Degrees) 547
	1594	31.6.36.1E xample547
	1595	31.6.37$$S QRT^XLFMTH (): Square Root547
	1596	31.6.37.1E xample548
	1597	31.6.38$$T AN^XLFMTH( ): Tangent (Radians) 548
	1598	31.6.38.1E xample548
	1599	31.6.39$$T ANDEG^XLFM TH(): Tang ent (Degre es)548
	1600	31.6.39.1E xample549
	1601	31.7Measur ement Func tions—XLFM SMT549
	1602	31.7.1$$BS A^XLFMSMT( ): Body Su rface Area Measureme nt549
	1603	31.7.1.1Ex amples549
	1604	31.7.2$$LE NGTH^XLFMS MT(): Conv ert Length Measureme nt550
	1605	31.7.2.1Ex amples550
	1606	31.7.3$$TE MP^XLFMSMT (): Conver t Temperat ure Measur ement551
	1607	31.7.3.1Ex amples551
	1608	31.7.4$$VO LUME^XLFMS MT(): Conv ert Volume Measureme nt552
	1609	31.7.4.1Ex amples552
	1610	31.7.5$$WE IGHT^XLFMS MT(): Conv ert Weight Measureme nt553
	1611	31.7.5.1Ex amples553
	1612	31.8String Functions —XLFSTR554
	1613	31.8.1$$CJ ^XLFSTR(): Center Ju stify Stri ng554
	1614	31.8.1.1Ex amples554
	1615	31.8.2$$IN VERT^XLFST R(): Inver t String55 5
	1616	31.8.2.1Ex ample555
	1617	31.8.3$$LJ ^XLFSTR(): Left Just ify String 555
	1618	31.8.3.1Ex amples556
	1619	31.8.4$$LO W^XLFSTR() : Convert String to Lowercase5 56
	1620	31.8.4.1Ex ample556
	1621	31.8.5$$RE PEAT^XLFST R(): Repea t String55 7
	1622	31.8.5.1Ex amples557
	1623	31.8.6$$RE PLACE^XLFS TR(): Repl ace String s557
	1624	31.8.6.1Ex amples558
	1625	31.8.7$$RJ ^XLFSTR(): Right Jus tify Strin g558
	1626	31.8.7.1Ex amples558
	1627	31.8.8$$SE NTENCE^XLF STR(): Con vert Strin g to Sente nce Case55 9
	1628	31.8.8.1Ex ample559
	1629	31.8.9$$ST RIP^XLFSTR (): Strip a String55 9
	1630	31.8.9.1Ex amples560
	1631	31.8.10$$T ITLE^XLFST R(): Conve rt String to Title C ase560
	1632	31.8.10.1E xample560
	1633	31.8.11$$T RIM^XLFSTR (): Trim S tring561
	1634	31.8.11.1E xamples561
	1635	31.8.12$$U P^XLFSTR() : Convert String to Uppercase5 62
	1636	31.8.12.1E xample562
	1637	31.9Utilit y Function s—XLFUTL56 3
	1638	31.9.1$$BA SE^XLFUTL( ): Convert Between T wo Bases56 3
	1639	31.9.1.1Ex amples563
	1640	31.9.2$$CC D^XLFUTL() : Append C heck Digit 564
	1641	31.9.2.1Ex amples564
	1642	31.9.3$$CN V^XLFUTL() : Convert Base 10 to Another B ase564
	1643	31.9.3.1Ex amples565
	1644	31.9.4$$DE C^XLFUTL() : Convert Another Ba se to Base 10565
	1645	31.9.4.1Ex ample565
	1646	31.9.5$$VC D^XLFUTL() : Verify I ntegrity56 6
	1647	31.9.5.1Ex amples566
	1648	31.10IP Ad dress Func tions—XLFI PV567
	1649	31.10.1$$C ONVERT^XLF IPV():Conv ert any IP Address t o Standard ized IP Ad dress Form at567
	1650	31.10.1.1E xamples567
	1651	31.10.2$$F ORCEIP4^XL FIPV(): Co nvert any IP Address to IPv456 8
	1652	31.10.2.1E xamples568
	1653	31.10.3$$F ORCEIP6^XL FIPV(): Co nvert any IP Address to IPv656 9
	1654	31.10.3.1E xamples570
	1655	31.10.4$$V ALIDATE^XL FIPV(): Va lidate IP Address Fo rmat570
	1656	31.10.4.1E xamples571
	1657	31.10.5$$V ERSION^XLF IPV: Show System Set tings for IPv6571
	1658	31.10.5.1E xamples572
	1659	31.11JSON Conversion Functions —XLFJSON57 2
	1660	31.11.1DEC ODE^XLFJSO N(): Conve rt a JSON object int o a closed array ref erence.572
	1661	31.11.1.1E xamples573
	1662	31.11.2ENC ODE^XLFJSO N(): Conve rt closed array or g lobal refe rence to a JSON obje ct.573
	1663	31.11.2.1E xamples574
	1664	31.11.3$$E SC^XLFJSON (): Escape string to JSON.574
	1665	31.11.3.1E xamples574
	1666	31.11.4$$U ES^XLFJSON (): Unesca pe JSON to a string. 575
	1667	31.11.4.1E xamples575
	1668	32XML Pars er (VistA) : Develope r Tools576
	1669	32.1Overvi ew576
	1670	32.1.1Even t-driven I nterface57 6
	1671	32.1.2Worl d Wide Web Consortiu m Document Object Mo del Specif ication576
	1672	32.1.3Enti ty Catalog 577
	1673	32.1.4Term Definitio ns and XML Parser Co ncept577
	1674	32.1.5Know n Issues57 8
	1675	32.1.5.1Un supported Character Encodings5 78
	1676	32.1.5.2Re trieval of External Entities U sing Non-S tandard Fi le Access Protocols5 78
	1677	32.1.5.3Fi le Access5 78
	1678	32.1.5.4En tity Subst itutions T ext578
	1679	32.1.5.5En forcing Wh itespace57 9
	1680	32.2Applic ation Prog ramming In terface (A PI)579
	1681	32.2.1$$AT TRIB^MXMLD OM(): XML— Get First or Next No de Attribu te Name579
	1682	32.2.2$$CH ILD^MXMLDO M(): XML—G et Parent Node’s Fir st or Next Child580
	1683	32.2.3$$CM NT^MXMLDOM (): XML—Ex tract Comm ent Text ( True/False )580
	1684	32.2.4CMNT ^MXMLDOM() : XML—Extr act Commen t Text (Tr ue/False)5 81
	1685	32.2.5DELE TE^MXMLDOM (): XML—De lete Docum ent Instan ce581
	1686	32.2.6$$EN ^MXMLDOM() : XML—Init ial Proces sing of XM L Document , Build In -memory Im age582
	1687	32.2.7$$NA ME^MXMLDOM (): XML—Ge t Element Name583
	1688	32.2.8$$PA RENT^MXMLD OM(): XML— Get Parent Node583
	1689	32.2.9$$SI BLING^MXML DOM(): XML —Get Sibli ng Node584
	1690	32.2.10$$T EXT^MXMLDO M(): XML—E xtract Non -markup Te xt (True/F alse)584
	1691	32.2.11TEX T^MXMLDOM( ): XML—Ext ract Non-m arkup Text (True/Fal se)585
	1692	32.2.12$$V ALUE^MXMLD OM(): XML— Get Attrib ute Value5 85
	1693	32.2.13EN^ MXMLPRSE() : XML—Even t Driven A PI586
	1694	32.2.13.1D etails587
	1695	32.2.13.2E xample589
	1696	32.2.14$$S YMENC^MXML UTL(): XML —Replace X ML Symbols with XML Encoding59 1
	1697	32.2.14.1E xample591
	1698	32.2.15$$X MLHDR^MXML UTL: XML—G et XML Mes sage Heade r591
	1699	32.2.15.1E xample592
	1700	33^XTMP Gl obal: Deve loper Tool s593
	1701	33.1Overvi ew593
	1702	33.2Rules for Use of the ^XTMP Global593
	1703	33.3SAC Ex emptions59 4
	1704	Glossary59 5
	1705	Index601
	1706
	1707	List of Fi gures
	1708
	1709	Figure 1: CCODE^XIPU TIL API—Ex ample4
	1710	Figure 2: POSTAL^XIP UTIL API—E xample 17
	1711	Figure 3: POSTAL^XIP UTIL API—E xample 27
	1712	Figure 4: POSTALB^XI PUTIL API— Example9
	1713	Figure 5: Alerts—Cre ating an a lert for a user (e.g ., #14)10
	1714	Figure 6: Alerts—Che cking that the alert was sent1 0
	1715	Figure 7: AHISTORY^X QALBUTL AP I—Example: Sample us e and form at of data returned1 4
	1716	Figure 8: AHISTORY^X QALBUTL AP I—Example: Basic str ucture of the nodes taken from the globa l for this entry as seen via a global ma p view of the ALERT TRACKING f ile (#8992 .1)14
	1717	Figure 9: ALERTDAT^X QALBUTL AP I—Example1 6
	1718	Figure 10: DELSTAT^X QALBUTL AP I—Example: Sample VA LUE array1 7
	1719	Figure 11: USERDATA^ XQALBUTL A PI—Example 21
	1720	Figure 12: SETUP^XQA LERT API—C all to sen d an alert sample31
	1721	Figure 13: SETUP^XQA LERT API—R esulting a lert, from View Aler ts option3 1
	1722	Figure 14: $$SETUP1^ XQALERT AP I—Call to send an al ert sample 35
	1723	Figure 15: $$SETUP1^ XQALERT AP I—Resultin g alert, f rom View A lerts opti on35
	1724	Figure 16: USER^XQAL ERT API—Ex ample37
	1725	Figure 17: FORWARD^X QALFWD API —Example38
	1726	Figure 18: SUROFOR^X QALSURO AP I—Example4 3
	1727	Figure 19: SUROLIST^ XQALSURO A PI—Example 44
	1728	Figure 20: DEVICE^XU DHGUI API— Example 1: DEVICES a rray displ aying samp le results 56
	1729	Figure 21: DEVICE^XU DHGUI API— Example 2: DEVICES a rray displ aying samp le results 56
	1730	Figure 22: DEVICE^XU DHGUI API— Example 3: DEVICES a rray displ aying samp le results 57
	1731	Figure 23: DEVICE^XU DHGUI API— Example 4: DEVICES a rray displ aying samp le results 57
	1732	Figure 24: ^%ZIS API —Example66
	1733	Figure 25: GSET^%ZIS S API—Exam ple79
	1734	Figure 26: OPEN^%ZIS UTL API—Ex ample83
	1735	Figure 27: Device Ha ndler—Issu ing form f eeds follo wing curre nt guideli nes86
	1736	Figure 28: Device Ha ndler—Alte rnate appr oach follo wing curre nt guideli nes87
	1737	Figure 29: Error Tra p—Example9 8
	1738	Figure 30: UNWIND^%Z TER API—Ma in code ex ample100
	1739	Figure 31: UNWIND^%Z TER API—Us age100
	1740	Figure 32: OPKG^XUHU I API—Exam ple of cre ating New Style Cros s-referenc es102
	1741	Figure 33: OPKG^XUHU I API—Samp le scenari o102
	1742	Figure 34: OPKG^XUHU I API—Exam ple of int ernal resu lts104
	1743	Figure 35: File Acce ss Securit y—Setting DLAYGO in a template 107
	1744	Figure 36: Host File s—Opening a Host fil e using th e ^%ZIS AP I111
	1745	Figure 37: CLOSE^%ZI SH API—Exa mple112
	1746	Figure 38: Host File s—Overflow lines in a Host fil e sample11 4
	1747	Figure 39: OPEN^%ZIS H API—Exam ple119
	1748	Figure 40: $$STATUS^ %ZISH API— Example120
	1749	Figure 41: F4^XUAF4 API—Exampl e124
	1750	Figure 42: LOOKUP^XU AF4 API—Ex ample127
	1751	Figure 43: MAIN^XUMF I API—Samp le output1 35
	1752	Figure 44: MAIN^XUMF P API—Disp laying ^TM P global f or PARAM v alues140
	1753	Figure 45: KIDS—Edit s and Dist ribution m enu option s142
	1754	Figure 46: KIDS—Choo sing a bui ld type sa mple144
	1755	Figure 47: KIDS—Popu lating a b uild entry by namesp ace145
	1756	Figure 48: KIDS—Copy ing a buil d entry145
	1757	Figure 49: KIDS—Scre en 1 of Ed it a Build sample148
	1758	Figure 50: KIDS—Scre en 2 of Ed it a Build : Selectin g files149
	1759	Figure 51: KIDS—Data dictionar y and data settings1 49
	1760	Figure 52: KIDS—Data dictionar y settings screen—DD Export Op tions151
	1761	Figure 53: KIDS—Part ial DD: Ch oosing DD levels (to p level an d Multiple ) to send; Data Dict ionary Num ber level1 51
	1762	Figure 54: KIDS—Part ial DD: Ch oosing DD levels (to p level an d Multiple ) to send; Field Num ber level1 52
	1763	Figure 55: KIDS—Sett ings for s ending dat a153
	1764	Figure 56: KIDS—Scre en 3 of Ed it a Build : Componen ts156
	1765	Figure 57: KIDS—Choo sing routi nes159
	1766	Figure 58: KIDS—Sele cting temp lates160
	1767	Figure 59: KIDS—Tran sport a Di stribution option: C reating a distributi on sample user dialo gue161
	1768	Figure 60: KIDS—Tran sport a Di stribution option: S ending via network ( PackMan me ssage) sam ple user d ialogue162
	1769	Figure 61: KIDS—Mult i-package builds sam ple163
	1770	Figure 62: KIDS—Expo rting glob al distrib utions sam ple164
	1771	Figure 63: KIDS—Dial ogue when the XPDNOQ UE variabl e is set t o disable queuing168
	1772	Figure 64: KIDS—”DIS ABLE” defa ult prompt during in stallation s168
	1773	Figure 65: KIDS—”MOV E routines ” default prompt dur ing instal lations169
	1774	Figure 66: KIDS—Envi ronment Ch eck routin e sample17 0
	1775	Figure 67: KIDS—PRE- TRANSPORTA TION ROUTI NE field s ample171
	1776	Figure 68: KIDS—Scre en 4 of Ed it a Build sample174
	1777	Figure 69: KIDS—Pre- install qu estion (se tting up) sample176
	1778	Figure 70: KIDS—Appe arance of question d uring inst allation17 6
	1779	Figure 71: KIDS—Usin g checkpoi nts with c allbacks: combined p re- and po st-install routine17 9
	1780	Figure 72: KIDS—Requ ired build s sample18 1
	1781	Figure 73: KIDS—Patc h Applicat ion Histor y sample18 3
	1782	Figure 74: KIDS—Erro rs Logged in Alpha/B eta Test ( QUEUED) op tion186
	1783	Figure 75: Alpha/Bet a Test Opt ion Usage Menu optio ns187
	1784	Figure 76: Actual Us age of Alp ha/Beta Te st Options option—Sa mple Optio n Usage re port187
	1785	Figure 77: Enter/Edi t Kernel S ite Parame ters—Sampl e user dia logue189
	1786	Figure 78: Menu Mana ger—Edit o ptions [XU EDITOPT]20 7
	1787	Figure 79: Programme r Options menu optio ns—Toolkit miscellan eous tools 221
	1788	Figure 80: Calling t he ^%Z Edi tor—Sample user entr ies222
	1789	Figure 81: ^%Z Edito r—Displayi ng a routi ne using t he ZP comm and223
	1790	Figure 82: ^%Z Edito r—Listing edit comma nds223
	1791	Figure 83: ^%Z Edito r—Line mod e help inf ormation22 4
	1792	Figure 84: ^%Z Edito r—Replace mode editi ng help in formation2 24
	1793	Figure 85: ACTION me nu—Sample user entri es224
	1794	Figure 86: $$FMNAME^ XLFNAME AP I—Example: Convertin g an HL7 f ormatted n ame to a s tandard na me, and re turning th e componen ts in an a rray237
	1795	Figure 87: NAMECOMP^ XLFNAME AP I—Example2 41
	1796	Figure 88: STDNAME^X LFNAME API —Example25 0
	1797	Figure 89: UPDCOMP^X LFNAME2 AP I—Example2 53
	1798	Figure 90: OWNSKEY^X USRB API—E xample272
	1799	Figure 91: XQSERVER— Default bu lletin274
	1800	Figure 92: XU USER S IGN-ON—Sam ple ZZTALK Protocol2 78
	1801	Figure 93: XU USER S TART-UP op tion—Sampl e signon a ction-type option279
	1802	Figure 94: Applicati on Proxy E xample (Go od)287
	1803	Figure 95: Applicati on Proxy E xample (Go od)—Displa yed using Proxy User List opti on287
	1804	Figure 96: Applicati on Proxy E xample (Ba d) (1 of 2 )288
	1805	Figure 97: Applicati on Proxy E xample (Ba d) (2 of 2 )288
	1806	Figure 98: $$ADD^XUS ERNEW API— Example of adding a new user29 1
	1807	Figure 99: Spooling— Sending ou tput to th e spooler (and pre-d efining ZT IO)299
	1808	Figure 100 : Spooling —Allowing output to go the spo oler (with out pre-de fining ZTI O)299
	1809	Figure 101 : TaskMan— Sample cod e allowing users to select whe ther a job is queued or not an d the outp ut device to use309
	1810	Figure 102 : TaskMan— Sample cod e printing to a devi ce using s aved varia bles309
	1811	Figure 103 : $$DEV^XU TMDEVQ API —Example: Sample cod e314
	1812	Figure 104 : EN^XUTMD EVQ API—Sa mple repor t316
	1813	Figure 105 : $$NODEV^ XUTMDEVQ A PI—Sample code317
	1814	Figure 106 : $$QQ^XUT MDEVQ API— Sample cod e320
	1815	Figure 107 : $$REQQ^X UTMDEVQ AP I—Sample c ode322
	1816	Figure 108 : ^%ZTLOAD API—Print queuer sa mple code3 28
	1817	Figure 109 : ^%ZTLOAD API—Sampl e code330
	1818	Figure 110 : ^%ZTLOAD API—Sampl e code exe cution332
	1819	Figure 111 : ^%ZTLOAD API—Sampl e output33 2
	1820	Figure 112 : REQ^%ZTL OAD API—Sa mple code3 40
	1821	Figure 113 : ^%ZTLOAD API—Sampl e code exe cution342
	1822	Figure 114 : ^%ZTLOAD API—Sampl e output34 2
	1823	Figure 115 : Toolkit— Replacemen t relation ships: Dat a standard ization347
	1824	Figure 116 : .03 DUPL ICATE TEST ROUTINE—V ariables p assed to t he test ro utine360
	1825	Figure 117 : Special Processing Routine E xamples—Ca ndidate Co llection R outine for Patient M erge364
	1826	Figure 118 : Special Processing Routine E xamples—Na me Test Ro utine for a Patient Merge366
	1827	Figure 119 : Special Processing Routine E xamples—Da te of Birt h test Rou tine for a Patient M erge367
	1828	Figure 120 : $$MAKEUR L^XTHCURL API—Exampl e376
	1829	Figure 121 : LKUP^XTL KMGR API—E xample 1: Standard L ookup; Sin gle term e ntered387
	1830	Figure 122 : LKUP^XTL KMGR API—E xample 2: Standard L ookup; Mul tiple term s entered3 88
	1831	Figure 123 : LKUP^XTL KMGR API—E xample 3: Display mi nimized by setting t he 3rd par ameter = 0 389
	1832	Figure 124 : LKUP^XTL KMGR API—E xample 4: MTLU with screen dis play turne d off390
	1833	Figure 125 : XTENT: L ist Unit T est Entry Points395
	1834	Figure 126 : XTROU: L ist of Rou tines Cont aining Add itional Te sts395
	1835	Figure 127 : Sample o utput from the M Uni t test too l—Verbose3 99
	1836	Figure 128 : GETIREF^ XTID API—E xample 141 5
	1837	Figure 129 : Routine Tools—Menu options42 8
	1838	Figure 130 : %Index o f Routines option—Sa mple user entries430
	1839	Figure 131 : Verifier Tools—Men u options4 36
	1840	Figure 132 : Programm er Options —Menu opti ons: Toolk it verific ation tool s437
	1841	Figure 133 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a routi ne name on ly (1 of 3 )445
	1842	Figure 134 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a build name (2 o f 3)447
	1843	Figure 135 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a packa ge name (3 of 3)448
	1844	Figure 136 : F - Bloc k structur e mismatch —Sample co de error45 0
	1845	Figure 137 : F - GO o r DO misma tch from b lock struc ture (M45) —Sample co de error45 1
	1846	Figure 138 : F - Labe l is not v alid—Sampl e code err or451
	1847	Figure 139 : API - St ar our pou nd READ us ed—Syntact ic variati on (1 of 2 )459
	1848	Figure 140 : API - St ar our pou nd READ us ed—Syntact ic variati on (2 of 2 )459
	1849	Figure 141 : $$LOOKUP ^XUSER API —Example 1 : Showing confirmati on prompt4 74
	1850	Figure 142 : $$LOOKUP ^XUSER API —Example 2 : Suppress ing confir mation pro mpt474
	1851	Figure 143 : $$LOOKUP ^XUSER API —Example 3 : Terminat ed user474
	1852	Figure 144 : SAY^XGF API—Exampl e 1: READ a name492
	1853	Figure 145 : $$READ^X GF API—Exa mple 2: Ac cept only Up-Arrow ( “↑”) and D own-Arrow (“↓”) keys 492
	1854	Figure 146 : $$CRC16^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (1 of 2)501
	1855	Figure 147 : $$CRC16^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (2 of 2)501
	1856	Figure 148 : $$CRC16^ XLFCRC API —Example 2 501
	1857	Figure 149 : $$CRC32^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (1 of 2)502
	1858	Figure 150 : $$CRC32^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (2 of 2)502
	1859	Figure 151 : $$CRC32^ XLFCRC API —Example 2 503
	1860	Figure 152 : XML Docu ment (left )—Tree str ucture Dia gram (righ t)574
	1861	Figure 153 : VistA XM L Parser U se—Example : Create X ML file587
	1862	Figure 154 : VistA XM L Parser U se Example —Invoke SA X Interfac e587
	1863	Figure 155 : VistA XM L Parser U se Example —Check DOM Interface 587
	1864	Figure 156 : VistA XM L Parser U se Example —List All Sibling No des588
	1865
	1866	List of Ta bles
	1867
	1868	Table 1: D ocumentati on symbol descriptio nslxi
	1869	Table 2: A lerts—Rela ted terms and defini tions12
	1870	Table 3: H ost file A PIs—Defini tions111
	1871	Table 4: M AIN^XUMFP( ): Master File Param eters API— QRD: Query Definitio n137
	1872	Table 5: M AIN^XUMFP( ): Master File Param eters API— XCN Data T ype of QRD WHO Param eter137
	1873	Table 6: M AIN^XUMFP( ): Master File Param eters API— CE Data Ty pe of QRD WHAT Param eter138
	1874	Table 7: M AIN^XUMFP( ): Master File Param eters API— MFI: Maste r File Ide ntificatio n138
	1875	Table 8: M AIN^XUMFP( ): Master File Param eters API— MFE: Maste r File Ent ry138
	1876	Table 9: M AIN^XUMFP( ): Master File Param eters API— [Z...] Seg ments Para meters138
	1877	Table 10: MAIN^XUMFP (): Master File Para meters API —Files Inv olving Sub -records a nd Extende d Referenc e139
	1878	Table 11: KIDS—Optio ns support ing softwa re applica tion build s and expo rts143
	1879	Table 12: KIDS—Funct ional layo ut, Edit a Build146
	1880	Table 13: KIDS—Data installati on actions 153
	1881	Table 14: KIDS—Optio n and prot ocol insta llation ac tions157
	1882	Table 15: KIDS—Key v ariables d uring the environmen t check166
	1883	Table 16: KIDS—Actio ns based o n environm ent check conclusion s168
	1884	Table 17: KIDS—Insta llation: X PDDIQ arra y sample16 9
	1885	Table 18: KIDS—Envir onment Che ck—XPDDIQ array samp le169
	1886	Table 19: KIDS—Key p arameters during the pre- and post-insta ll routine s172
	1887	Table 20: KIDS—Key v ariables d uring the pre- and p ost-instal l routines 172
	1888	Table 21: KIDS—DIR i nput value s for KIDS install q uestions17 4
	1889	Table 22: KIDS—Funct ions using checkpoin ts with ca llbacks177
	1890	Table 23: KIDS—Funct ions using checkpoin ts without callbacks 180
	1891	Table 24: KIDS—Requi red builds installat ion action s181
	1892	Table 25: KIDS—Natio nal PACKAG E file fie ld updates 182
	1893	Table 26: Alpha/Beta Tracking— KERNEL SYS TEM PARAME TERS file (#8989.3) field setu p for KIDS 184
	1894	Table 27: Alpha/Beta Tracking— BUILD file (#9.6) fi eld setup for KIDS18 5
	1895	Table 28: Miscellane ous Tools— Direct Mod e Utilitie s221
	1896	Table 29: ^%ZOSF API —Global no des260
	1897	Table 30: Key variab le setup—S erver opti ons273
	1898	Table 31: TaskMan—ZT REQ piece and equiva lent REQ^Z TLOAD vari able306
	1899	Table 32: $$GETURL^X THC10—Comm on HTTP St atus Codes Returned3 74
	1900	Table 33: Parameter Tool—Param eter entit y levels40 0
	1901	Table 34: Routine To ols—Direct Mode Util ities427
	1902	Table 35: Verificati on Tools—D irect Mode Utilities 435
	1903	Table 36: XINDEX—Typ es of find ings (cate gory codes or flags) 441
	1904	Table 37: XINDEX—Lis t of the e rror condi tions (mes sages) fla gged: Grou ped by cat egory and listed alp habeticall y); messag es are sto red in XIN DX1 routin e442
	1905	Table 38: XGF Functi on Library —Minimum M implement ation feat ures requi red483
	1906	Table 39: XGF Functi on Library —Demo func tional div ision484
	1907	Table 40: XGF Functi on Library —Mnemonics for keys that termi nate READs 491
	1908	Table 41: $$LENGTH^X LFMSMT API —Valid uni ts550
	1909	Table 42: $$TEMP^XLF MSMT API—V alid units 551
	1910	Table 43: $$VOLUME^X LFMSMT API —Valid uni ts552
	1911	Table 44: $$WEIGHT^X LFMSMT API —Valid uni ts553
	1912	Table 45: XML ENTITY CATALOG f ile (#950) —Stores ex ternal ent ities and assoc publ ic identif iers574
	1913	Table 46: XML Parser —Event typ es584
	1914
	1915
	1916	Orientatio n
	1917	How to Use this Manu al
	1918	This manua l provides advice an d instruct ion about Kernel 8.0 and Kerne l Toolkit 7.3 Applic ation Prog ramming In terfaces ( APIs), Dir ect Mode U tilities, and other informatio n for Vete rans Healt h Informat ion System s and Tech nology Arc hitecture (VistA) ap plication developers .
	1919	Intended A udience
	1920	The intend ed audienc e of this manual is the follow ing stakeh olders:
	1921	Enterprise Program M anagement Office (EP MO)—VistA legacy dev elopment t eams.
	1922	System Adm inistrator s—System a dministrat ors at Dep artment of Veterans Affairs (V A) regiona l sites wh o are resp onsible fo r computer managemen t and syst em securit y on the V istA M Ser vers.
	1923	Informatio n Security Officers (ISOs)—Per sonnel at VA sites r esponsible for syste m security .
	1924	Product Su pport (PS) .
	1925	Disclaimer s
	1926	Software D isclaimer
	1927	This soft ware was d eveloped a t the Depa rtment of Veterans A ffairs (VA ) by emplo yees of th e Federal Government in the co urse of th eir offici al duties. Pursuant to title 1 7 Section 105 of the United St ates Code this softw are is not subject t o copyrigh t protecti on and is in the pub lic domain . VA assum es no resp onsibility whatsoeve r for its use by oth er parties , and make s no guara ntees, exp ressed or implied, a bout its q uality, re liability, or any ot her charac teristic. We would a ppreciate acknowledg ement if t he softwar e is used. This soft ware can b e redistri buted free ly provide d that any derivativ e works be ar some no tice that they are d erived fro m it.
	1928	CAUTION: K ernel rout ines shoul d never be modified at the sit e. If ther e is an im mediate na tional req uirement, the change s should b e made by emergency Kernel pat ch. Kernel software is subject to FDA re gulations requiring Blood Bank Review, a mong other limitatio ns. Line 3 of all Ke rnel routi nes states : Per V A Directiv e 6402 (pe nding sign ature), th is routine should no t be modif ied.
	1929	CAUTION: T o protect the securi ty of Vist A systems, distribut ion of thi s software for use o n any othe r computer system by VistA sit es is proh ibited. Al l requests for copie s of Kerne l for non- VistA use should be referred t o the Vist A site’s l ocal Offic e of Infor mation Fie ld Office (OIFO).
	1930	Documentat ion Discla imer
	1931	This manua l provides an overal l explanat ion of usi ng kernel; however, no attempt is made t o explain how the ov erall Vist A programm ing system is integr ated and m aintained. Such meth ods and pr ocedures a re documen ted elsewh ere. We su ggest you look at th e various VA Interne t and Intr anet Share Point site s and webs ites for a general o rientation to VistA. For examp le, visit the Office of Inform ation and Technology (OI&T) En terprise P rogram Man agement Of fice (EPMO ) Intranet Website.
	1932	DISCLAIMER : The appe arance of any extern al hyperli nk referen ces in thi s manual d oes not co nstitute e ndorsement by the De partment o f Veterans Affairs ( VA) of thi s Website or the inf ormation, products, or service s containe d therein. The VA do es not exe rcise any editorial control ov er the inf ormation y ou find at these loc ations. Su ch links a re provide d and are consistent with the stated pur pose of th is VA Intr anet Servi ce.
	1933	Documentat ion Conven tions
	1934	This manua l uses sev eral metho ds to high light diff erent aspe cts of the material:
	1935	Various sy mbols are used throu ghout the documentat ion to ale rt the rea der to spe cial infor mation. Ta ble 1 give s a descri ption of e ach of the se symbols :
	1936	Table 1: D ocumentati on symbol descriptio ns
	1937	Symbol
	1938	Descriptio n
	1939
	1940	NOTE / REF : Used to inform the reader of general i nformation including reference s to addit ional read ing materi al.
	1941
	1942	CAUTION / RECOMMENDA TION / DIS CLAIMER: U sed to cau tion the r eader to t ake specia l notice o f critical informati on.
	1943
	1944	Descriptiv e text is presented in a propo rtional fo nt (as rep resented b y this fon t).
	1945	Convention s for disp laying TES T data in this docum ent are as follows:
	1946	The first three digi ts (prefix ) of any S ocial Secu rity Numbe rs (SSN) b egin with either “00 0” or “666 ”.
	1947	Patient an d user nam es are for matted as follows:
	1948	<Applicati on Name/Ab breviation /Namespace >PATIENT,< N>
	1949	<Applicati on Name/Ab breviation /Namespace >USER,<N>
	1950	Where:
	1951	<Applicati on Name/Ab breviation /Namespace > is defin ed in the Approved A pplication Abbreviat ions docum ent.
	1952	<N> repres ents the f irst name as a numbe r spelled out and in cremented with each new entry.
	1953	For exampl e, in Kern el (XU or KRN) test patient an d user nam es would b e document ed as foll ows:
	1954	KRNPATIENT ,ONE; KRNP ATIENT,TWO ; KRNPATIE NT,THREE; … KRNPATIE NT,14; etc .
	1955	KRNUSER,ON E; KRNUSE, TWO; KRNUS E,THREE; … KRNUSE,14 ; etc.
	1956	“Snapshot s” of comp uter onlin e displays (i.e., sc reen captu res/dialog ues) and c omputer so urce code is shown i n a non-pr oportional font and may be enc losed with in a box.
	1957	User’s res ponses to online pro mpts are b oldface an d (optiona lly) highl ighted in yellow (e. g., <Enter >).
	1958	Emphasis w ithin a di alogue box is boldfa ce and (op tionally) highlighte d in blue (e.g., STA NDARD LIST ENER: RUNN ING).
	1959	Some softw are code r eserved/ke y words ar e boldface with alte rnate colo r font.
	1960	References to “<Ente r>” within these sna pshots ind icate that the user should pre ss the Ent er key on the keyboa rd. Other special ke ys are rep resented w ithin < > angle brac kets. For example, p ressing th e PF1 key can be rep resented a s pressing <PF1>.
	1961	Author’s c omments ar e displaye d in itali cs or as “ callout” b oxes.
	1962	NOTE: Call out boxes refer to l abels or d escription s usually enclosed w ithin a bo x, which p oint to sp ecific are as of a di splayed im age.
	1963	This manua l refers t o the M pr ogramming language. Under the 1995 Ameri can Nation al Standar ds Institu te (ANSI) standard, M is the p rimary nam e of the M UMPS progr amming lan guage, and MUMPS is considered an altern ate name. This manua l uses the name M.
	1964	Descriptio ns of dire ct mode ut ilities ar e prefaced with the standard M “>” promp t to empha size that the call i s to be us ed only in direct mo de. They a lso includ e the M co mmand used to invoke the utili ty. The fo llowing is an exampl e:
	1965	>D ^XUP
	1966	The follow ing conven tions are used with regards to APIs:
	1967	Headings f or develop er API des criptions (e.g., sup ported for use in ap plications and on th e Database Integrati on Committ ee [DBIC] list) incl ude the ro utine tag (if any), the caret (“^”) used when call ing the ro utine, and the routi ne name. T he followi ng is an e xample:
	1968	EN1^XQH
	1969	For APIs t hat take i nput param eter, the input para meter is l abeled “re quired” wh en it is a required input para meter and labeled “o ptional” w hen it is an optiona l input pa rameter.
	1970	For APIs t hat take p arameters, parameter s are show n in lower case and v ariables a re shown i n uppercas e. This is to convey that the parameter name is me rely a pla ceholder; M allows y ou to pass a variabl e of any n ame as the parameter or even a string li teral (if the parame ter is not being pas sed by ref erence). T he followi ng is an e xample of the format ting for i nput param eters:
	1971	XGLMSG^XGL MSG(msg_ty pe,[.]var[ ,timeout])
	1972	Rectangula r brackets [ ] aroun d a parame ter are us ed to indi cate that passing th e paramete r is optio nal. Recta ngular bra ckets arou nd a leadi ng period [.] in fro nt of a pa rameter in dicate tha t you can optionally pass that parameter by refere nce.
	1973	All APIs a re categor ized by fu nction. Th is categor ization is subjectiv e and subj ect to cha nge based on feedbac k from the developme nt communi ty. In add ition, som e APIs cou ld fall un der multip le categor ies; howev er, they a re only li sted once under a ch osen categ ory.APIs w ithin a ca tegory are first sor ted alphab etically b y Routine name and t hen within routine n ame are so rted alpha betically by Tag ref erence. Th e “$$”, “^ ”, or “^%” prefixes on APIs is ignored w hen alphab etizing.
	1974	All upperc ase is res erved for the repres entation o f M code, variable n ames, or t he formal name of op tions, fie ld/file na mes, and s ecurity ke ys (e.g., the XUPROG MODE secur ity key).
	1975	NOTE: Othe r software code (e.g ., Delphi/ Pascal and Java) var iable name s and file /folder na mes can be written i n lower or mixed cas e (e.g., C amelCase).
	1976	Documentat ion Naviga tion
	1977	This docum ent uses M icrosoft® Word’s bui lt-in navi gation for internal hyperlinks . To add B ack and Fo rward navi gation but tons to th e toolbar, do the fo llowing:
	1978	Right-clic k anywhere on the cu stomizable Toolbar i n Word (no t the Ribb on section ).
	1979	Select Cus tomize Qui ck Access Toolbar fr om the sec ondary men u.
	1980	Select the drop-down arrow in the “Choos e commands from:” bo x.
	1981	Select All Commands from the d isplayed l ist.
	1982	Scroll thr ough the c ommand lis t in the l eft column until you see the B ack comman d (circle with arrow pointing left).
	1983	Select/Hig hlight the Back comm and and se lect Add t o add it t o your cus tomized to olbar.
	1984	Scroll thr ough the c ommand lis t in the l eft column until you see the F orward com mand (circ le with ar row pointi ng right).
	1985	Select/Hig hlight the Forward c ommand and select Ad d to add i t to the c ustomized toolbar.
	1986	Select OK.
	1987	You can no w use thes e Back and Forward c ommand but tons in th e Toolbar to navigat e back and forth in the Word d ocument wh en selecti ng hyperli nks within the docum ent.
	1988	NOTE: This is a one- time setup and is au tomaticall y availabl e in any o ther Word document o nce you in stall it o n the Tool bar.
	1989	How to Obt ain Techni cal Inform ation Onli ne
	1990	Exported V istA M Ser ver-based software f ile, routi ne, and gl obal docum entation c an be gene rated usin g Kernel, MailMan, a nd VA File Man utilit ies.
	1991	NOTE: Meth ods of obt aining spe cific tech nical info rmation on line is in dicated wh ere applic able under the appro priate sec tion.REF: For furthe r informat ion, see t he Kernel Technical Manual.
	1992	Help at Pr ompts
	1993	VistA M Se rver-based software provides o nline help and commo nly used s ystem defa ult prompt s. Users a re encoura ged to ent er questio n marks at any respo nse prompt . At the e nd of the help displ ay, you ar e immediat ely return ed to the point from which you started. This is an easy way to learn a bout any a spect of V istA M Ser ver-based software.
	1994	Obtaining Data Dicti onary List ings
	1995	Technical informatio n about Vi stA M Serv er-based f iles and t he fields in files i s stored i n data dic tionaries (DD). You can use th e List Fil e Attribut es option [DILIST] o n the Data Dictionar y Utilitie s menu [DI DDU] in V A FileMan to print f ormatted d ata dictio naries.
	1996	REF: For d etails abo ut obtaini ng data di ctionaries and about the forma ts availab le, see th e “List Fi le Attribu tes” secti on in the “File Mana gement” se ction in t he VA File Man Advanc ed User Ma nual.
	1997	Assumption s
	1998	This manua l is writt en with th e assumpti on that th e reader i s familiar with the following:
	1999	VistA comp uting envi ronment:
	2000	Kernel—Vis tA M Serve r software
	2001	VA FileMan data stru ctures and terminolo gy—VistA M Server so ftware
	2002	Microsoft® Windows e nvironment
	2003	M programm ing langua ge
	2004	Reference Materials
	2005	Readers wh o wish to learn more about Ker nel should consult t he followi ng:
	2006	Kernel Rel ease Notes
	2007	Kernel Ins tallation Guide
	2008	Kernel Sys tems Manag ement Guid e
	2009	Kernel Dev eloper’s G uide (this manual)
	2010	Kernel Tec hnical Man ual
	2011	Kernel Sec urity Tool s Manual
	2012	Kernel VA Intranet W ebsite.
	2013	This site contains o ther infor mation and provides links to a dditional documentat ion.
	2014	VistA docu mentation is made av ailable on line in Mi crosoft® W ord format and in Ad obe® Acrob at Portabl e Document Format (P DF). The P DF documen ts must be read usin g the Adob e® Acrobat Reader, w hich is fr eely distr ibuted by Adobe® Sys tems Incor porated at : http://w ww.adobe.c om/
	2015	VistA docu mentation can be dow nloaded fr om the VA Software D ocument Li brary (VDL ): http:// www. DOMAIN /vdl/
	2016	REF: Kerne l manuals are locate d on the V DL at: htt p://www. DOMAIN /vdl/appli cation.asp ?appid=10
	2017	VistA docu mentation and softwa re can als o be downl oaded from the Produ ct Support (PS) Anon ymous Dire ctories.
	2018
	2019
	2020	Introducti on
	2021	This manua l provides descripti ve informa tion about Kernel fo r use by a pplication developer s. Kernel provides d evelopers with a num ber of too ls. These tools incl ude Applic ation Prog ramming In terfaces ( APIs) and direct-mod e utilitie s. These t ools let y ou create applicatio ns that ar e fully in tegrated w ith Kernel and that take advan tage of Ke rnel’s fea tures.
	2022	This manua l assumes that the r eader is f amiliar wi th the com puting env ironment o f the VA’s Veterans Health Inf ormation S ystems and Technolog y Architec ture (Vist A), and un derstands VA FileMan data stru ctures and terminolo gy. Unders tanding of the M pro gramming l anguage is required for this m anual. No attempt is made to e xplain how the overa ll VistA p rogramming system is integrate d and main tained; su ch methods and proce dures are documented elsewhere .
	2023	You can fi nd develop er informa tion in th e sections and sub-s ections of this manu al that co ntain “Dev eloper Too ls” in the ir titles. You might want to c oncentrate on those sections i n this man ual that c ould affec t your pro ject. For example, i f you are working on a project requiring tasking a job, you should fam iliarize y ourself wi th the inf ormation i n the “Tas kMan: Deve loper Tool s” section .
	2024	Kernel pro vides deve lopers wit h a number of tools. These too ls include Applicati on Program ming Inter faces (API s), and di rect-mode utilities. These too ls let you create ap plications that are fully inte grated wit h Kernel a nd that ta ke advanta ge of Kern el’s featu res.
	2025	The Kernel Developer ’s Guide i s divided into secti ons, based on the fo llowing fu nctional A PI/Direct Mode Utili ty categor ies within Kernel (l isted alph abetically ):
	2026	Address Hy giene: Dev eloper Too ls
	2027	Alerts: De veloper To ols
	2028	Common Ser vices: Dev eloper Too ls
	2029	Device Han dler: Deve loper Tool s
	2030	Domain Nam e Service (DNS): Dev eloper Too ls
	2031	Electronic Signature s: Develop er Tools
	2032	Error Proc essing: De veloper To ols
	2033	Field Moni toring: De veloper To ols
	2034	File Acces s Security : Develope r Tools
	2035	Help Proce ssor: Deve loper Tool s
	2036	Host Files : Develope r Tools
	2037	Institutio n File: De veloper To ols
	2038	Kernel Ins tallation and Distri bution Sys tem (KIDS) : Develope r Tools
	2039	Lock Manag er: Develo per Tools
	2040	Toolkit—M Unit
	2041	Menu Manag er: Develo per Tools
	2042	Miscellane ous: Devel oper Tools
	2043	Name Stand ardization : Develope r Tools
	2044	National P rovider Id entifier ( NPI): Deve loper Tool s
	2045	Operating System (OS ) Interfac e: Develop er Tools
	2046	Security K eys: Devel oper Tools
	2047	Server Opt ions: Deve loper Tool s
	2048	Signon/Sec urity: Dev eloper Too ls
	2049	Spooling: Developer Tools
	2050	TaskMan: D eveloper T ools
	2051	Toolkit: D eveloper T ools
	2052	Unwinder: Developer Tools
	2053	User: Deve loper Tool s
	2054	XGF Functi on Library : Develope r Tools
	2055	XLF Functi on Library : Develope r Tools
	2056	Date Funct ions—XLFDT
	2057	Hyperbolic Trigonome tric Funct ions—XLFHY PER
	2058	IP Address Functions —XLFIPV
	2059	Mathematic al Functio ns—XLFMTH
	2060	Measuremen t Function s—XLFMSMT
	2061	String Fun ctions—XLF STR
	2062	Utility Fu nctions—XL FUTL
	2063	XML Parser (VistA): Developer Tools
	2064	REF: For g eneral use r informat ion and sy stem manag er informa tion, see the Kernel Systems M anagement Guide.Inst ructions f or install ing Kernel are provi ded in the Kernel In stallation Guide. Th is guide a lso includ es informa tion about software applicatio n manageme nt (e.g., recommende d settings for site parameters and sched uling time frames fo r tasked o ptions).In formation on recomme nded syste m configur ation and setting Ke rnel’s sit e paramete rs, as wel l as lists of files, routines, options, and other components are docum ented in t he Kernel Technical Manual.Inf ormation a bout manag ing comput er securit y, which i ncludes a detailed d escription of techni ques that can be use d to monit or and aud it computi ng activit y, is pres ented in t he Kernel Security T ools Manua l.
	2065
	2066
	2067	Address Hy giene: Dev eloper Too ls
	2068	Applicatio n Programm ing Interf ace (API)
	2069	Several AP Is are ava ilable for developer s to work with addre ss hygiene . These AP Is are des cribed bel ow.
	2070	CCODE^XIPU TIL(): FIP S Code Dat a
	2071	Reference Type:Suppo rted
	2072	Category:A ddress Hyg iene
	2073	ICR #:3618
	2074	Descriptio n:This API returns a ll the dat a associat ed for a F IPS code.
	2075	Format:CCO DE^XIPUTIL (fips,.xip c)
	2076	Input Para meters:fip s:(require d) FIPS Co de.
	2077	Output Par ameters:xi pc:An arra y containi ng the fol lowing:
	2078	XIPC(“COUN TY”)—Count y associat ed with th is FIPS co de
	2079	XIPC(“FIPS CODE”)—5- digit FIPS county co de
	2080	XIPC(“INAC TIVE DATE” )—Date the FIPS code was inact ivated
	2081	XIPC(“LATI TUDE”)—Est imated Lat itude of t he county
	2082	XIPC(“LONG ITUDE”)—Es timated Lo ngitude of the count y
	2083	XIPC(“STAT E”)—State associated with this FIPS code
	2084	XIPC(“STAT E POINTER” )—Pointer to the sta te in the STATE file (#5)
	2085	XIPC(“ERRO R”)—Errors encounter ed during lookup
	2086	Example
	2087	Figure 1: CCODE^XIPU TIL API—Ex ample
	2088	>S ZFIPS=5 4041
	2089
	2090	>S ZTMP=“”
	2091
	2092	>D CCODE^X IPUTIL(ZFI PS,.ZTMP)
	2093
	2094	>ZW ZTMP,Z FIPS
	2095	ZFIPS=5404 1
	2096	ZTMP=
	2097	ZTMP(“COUN TY”)=LEWIS
	2098	ZTMP(“FIPS CODE”)=54 041
	2099	ZTMP(“INAC TIVE DATE” )=
	2100	ZTMP(“LATI TUDE”)=39: 00N
	2101	ZTMP(“LONG ITUDE”)=80 :28W
	2102	ZTMP(“STAT E”)=WEST V IRGINIA
	2103	ZTMP(“STAT E POINTER” )=54
	2104
	2105	$$FIPS^XIP UTIL(): FI PS Code fo r ZIP Code
	2106	Reference Type:Suppo rted
	2107	Category:A ddress Hyg iene
	2108	ICR #:3618
	2109	Descriptio n:This ext rinsic fun ction retu rns the Fe deral Info rmation Pr ocessing S tandard (F IPS) Code associated with the Postal Cod e.
	2110	Format:$$F IPS^XIPUTI L(pcode)
	2111	Input Para meters:pco de:(requir ed) Postal Code for which the FIPS Code is returne d.
	2112	Output:ret urns:Retur ns the FIP S Code.
	2113
	2114	Example
	2115	>S X=$$FIP S^XIPUTIL( “26452”)
	2116
	2117	>W X
	2118	54041
	2119
	2120	$$FIPSCHK^ XIPUTIL(): Check for FIPS Code
	2121	Reference Type:Suppo rted
	2122	Category:A ddress Hyg iene
	2123	ICR #:3618
	2124	Descriptio n:This ext rinsic fun ction answ ers the qu estion as to whether or not a Federal In formation Processing Standard (FIPS) cod e exists. It returns the follo wing:
	2125	IEN—Intern al Entry N umber, if the FIPS c ode exists .
	2126	Zero (0)—F IPS Code d oes not ex ist.
	2127	Format:$$F IPSCHK^XIP UTIL(fips)
	2128	Input Para meters:fip s:(require d) FIPS Co de.
	2129	Output:ret urns:Retur ns:
	2130	IEN—Intern al Entry N umber, if the FIPS c ode exists .
	2131	Zero (0)—F IPS Code d oes not ex ist.
	2132
	2133	Examples
	2134	Example 1
	2135	>S X=$$FIP SCHK^XIPUT IL(“54041” )
	2136
	2137	>W X
	2138	335
	2139
	2140	Example 2
	2141	>S X=$$FIP SCHK^XIPUT IL(“54999” )
	2142
	2143	>W X
	2144	0
	2145
	2146	POSTAL^XIP UTIL(): ZI P Code Inf ormation
	2147	Reference Type:Suppo rted
	2148	Category:A ddress Hyg iene
	2149	ICR #:3618
	2150	Descriptio n:This API returns U nited Stat es Postal Service (U SPS)-relat ed data/in formation in an outp ut array ( see “Outpu t Paramete rs”) for t he preferr ed (defaul t) ZIP Cod e.
	2151	Format:POS TAL^XIPUTI L(pcode,.x ip)
	2152	Input Para meters:pco de:(requir ed) Postal Code for which data is return ed.
	2153	Output Par ameters:.x ip:An arra y containi ng the fol lowing:
	2154	XIP(“CITY” )—City tha t the Unit ed States Postal Ser vice (USPS ) assigned to this P CODE.
	2155	XIP(“CITY ABBREVIATI ON”)—USPS assigned a bbreviatio n.
	2156	XIP(“CITY KEY”)—USPS assigned city key.
	2157	XIP(“COUNT Y”)—County associate d with thi s PCODE.
	2158	XIP(“COUNT Y POINTER” )—Pointer to the cou nty in the COUNTY CO DE file (# 5.13).
	2159	XIP(“FIPS CODE”)—5-d igit FIPS code assoc iated with the count y.
	2160	XIP(“INACT IVE DATE”) —Date FIPS Code inac tive.
	2161	XIP(“LATIT UDE”)—Lati tude.
	2162	XIP(“LONGI TUDE”)—Lon gitude.
	2163	XIP(“POSTA L CODE”)—V alue used to look up postal da ta.
	2164	XIP(“PREFE RRED CITY KEY”)—USPS preferred (DEFAULT) city key.
	2165	XIP(“STATE ”)—State a ssociated with this PCODE.
	2166	XIP(“STATE POINTER”) —Pointer t o the stat e in the S TATE file (#5).
	2167	XIP(“UNIQU E KEY”)—Un ique looku p value.
	2168	XIP(“ERROR ”)—Errors encountere d during l ookup.
	2169	Examples
	2170	Example 1
	2171	Figure 2: POSTAL^XIP UTIL API—E xample 1
	2172	>S ZCODE=9 9991
	2173
	2174	>S ZTMP=“”
	2175
	2176	>D POSTAL^ XIPUTIL(ZC ODE,.ZTMP)
	2177
	2178	>ZW ZTMP,Z CODE
	2179	ZCODE=9999 1
	2180	ZTMP=
	2181	ZTMP(“CITY ”)=ANYCITY 1
	2182	ZTMP(“CITY ABBREVIAT ION”)=
	2183	ZTMP(“CITY KEY”)=Z22 802
	2184	ZTMP(“COUN TY”)=ANYCO UNTY1
	2185	ZTMP(“COUN TY POINTER ”)=2910
	2186	ZTMP(“FIPS CODE”)=06 075
	2187	ZTMP(“INAC TIVE DATE” )=
	2188	ZTMP(“LATI TUDE”)=39: 00N
	2189	ZTMP(“LONG ITUDE”)=80 :28W
	2190	ZTMP(“POST AL CODE”)= 99991
	2191	ZTMP(“PREF ERRED CITY KEY”)=Z22 802
	2192	ZTMP(“STAT E”)=ANYSTA TE1
	2193	ZTMP(“STAT E POINTER” )=6
	2194	ZTMP(“UNIQ UE KEY”)=9 99919Z2280 2
	2195
	2196	Example 2
	2197	Figure 3: POSTAL^XIP UTIL API—E xample 2
	2198	>S ZCODE=9 9992
	2199
	2200	>S ZTMP=“”
	2201
	2202	>D POSTAL^ XIPUTIL(ZC ODE,.ZTMP)
	2203
	2204	>ZW ZTMP,Z CODE
	2205	ZCODE=9999 2
	2206	ZTMP=
	2207	ZTMP(“CITY ”)=ANYCITY 2
	2208	ZTMP(“CITY ABBREVIAT ION”)=
	2209	ZTMP(“CITY KEY”)=Z22 296
	2210	ZTMP(“COUN TY”)=ANYCO UNTY2
	2211	ZTMP(“COUN TY POINTER ”)=2912
	2212	ZTMP(“FIPS CODE”)=06 001
	2213	ZTMP(“INAC TIVE DATE” )=
	2214	ZTMP(“POST AL CODE”)= 99992
	2215	ZTMP(“PREF ERRED CITY KEY”)=Z22 296
	2216	ZTMP(“STAT E”)=ANYSTA TE2
	2217	ZTMP(“STAT E POINTER” )=6
	2218	ZTMP(“UNIQ UE KEY”)=9 99929Z2229 6
	2219
	2220	POSTALB^XI PUTIL(): A ctive ZIP Codes
	2221	Reference Type:Suppo rted
	2222	Category:A ddress Hyg iene
	2223	ICR #:3618
	2224	Descriptio n:This API returns a ll of the active ZIP Codes for a single ZIP Code.
	2225	Format:POS TALB^XIPUT IL(pcode,. xip)
	2226	Input Para meters:pco de:(requir ed) Postal Code for which the data is be ing reques ted.
	2227	Output Par ameters:.x ip(n):The number of primary su bscripts i n an array :
	2228	XIP(n,“CIT Y”)—City t hat the US PS assigne d to this PCODE. An asterisk “ *” indicat es which c ity is PRE FERRED (DE FAULT).
	2229	XIP(n,“CIT Y KEY”)—US PS’s assig ned city k ey.
	2230	XIP(n, “CI TY ABBREVI ATION”)—US PS’s assig ned abbrev iation.
	2231	XIP(n,“COU NTY”)—Coun ty associa ted with t his PCODE.
	2232	XIP(n,“COU NTY POINTE R”)—Pointe r to the c ounty in C OUNTY CODE file (#5. 13).
	2233	XIP(n,“FIP S CODE”)—5 -digit FIP S code ass ociated wi th the cou nty
	2234	XIP(n,“POS TAL CODE”) —Value use d to look up postal data
	2235	XIP(n,“PRE FERRED CIT Y KEY”)—US PS preferr ed (DEFAUL T) city ke y.
	2236	XIP(n,“STA TE”)—State associate d with thi s PCODE.
	2237	XIP(n,“STA TE POINTER ”)—Pointer to the st ate in the STATE fil e (#5).
	2238	XIP(n,“UNI QUE KEY”)— Unique loo kup value.
	2239	XIP(“ERROR ”)—Errors encountere d during l ookup.
	2240	Example
	2241	Figure 4: POSTALB^XI PUTIL API— Example
	2242	>S ZCODE=2 6452
	2243
	2244	>S ZTMP=“”
	2245
	2246	>D POSTALB ^XIPUTIL(Z CODE,.ZTMP )
	2247
	2248	>ZW ZTMP,Z CODE
	2249	ZCODE=2645 2
	2250	ZTMP=2
	2251	ZTMP(1,“CI TY”)=WESTO N*
	2252	ZTMP(1,“CI TY ABBREVI ATION”)=
	2253	ZTMP(1,“CI TY KEY”)=X 29362
	2254	ZTMP(1,“CO UNTY”)=LEW IS
	2255	ZTMP(1,“CO UNTY POINT ER”)=335
	2256	ZTMP(1,“FI PS CODE”)= 54041
	2257	ZTMP(1,“PO STAL CODE” )=26452
	2258	ZTMP(1,“PR EFERRED CI TY KEY”)=X 29362
	2259	ZTMP(1,“ST ATE”)=WEST VIRGINIA
	2260	ZTMP(1,“ST ATE POINTE R”)=54
	2261	ZTMP(1,“UN IQUE KEY”) =26452X293 62
	2262	ZTMP(2,“CI TY”)=VALLE Y CHEL
	2263	ZTMP(2,“CI TY ABBREVI ATION”)=
	2264	ZTMP(2,“CI TY KEY”)=X 2A444
	2265	ZTMP(2,“CO UNTY”)=LEW IS
	2266	ZTMP(2,“CO UNTY POINT ER”)=335
	2267	ZTMP(2,“FI PS CODE”)= 54041
	2268	ZTMP(2,“PO STAL CODE” )=26452
	2269	ZTMP(2,“PR EFERRED CI TY KEY”)=X 29362
	2270	ZTMP(2,“ST ATE”)=WEST VIRGINIA
	2271	ZTMP(2,“ST ATE POINTE R”)=54
	2272	ZTMP(2,“UN IQUE KEY”) =26452X2A4 44
	2273
	2274
	2275
	2276	Alerts: De veloper To ols
	2277	Overview
	2278	An applica tion might want to i ssue an al ert to one or more u sers when certain co nditions a re met, su ch as depl eted stock levels or abnormal lab test r esults.
	2279	Alerts are usually g enerated t hrough API s. The SET UP^XQALERT API creat es an aler t.
	2280	You may wa nt to send alerts fr om within an applica tion progr am or as p art of a t rigger in a VA FileM an file. D evelopers and system administr ators are invited to discover imaginativ e ways to integrate alerts wit hin local and nation al program ming. Reme mber, howe ver, not t o overwhel m the user with aler ts.
	2281	Once you h ave sent a n alert, o ne way you can confi rm that th e alert wa s sent is to use the VA FileMa n Inquire option, an d examine the entry in the ALE RT file (# 8992) for the users to whom yo u sent the alert.
	2282	Figure 5: Alerts—Cre ating an a lert for a user (e.g ., #14)
	2283	; send ale rt
	2284	S XQA(14)= “”,XQAMSG= “Enter pro gress note ”,XQAOPT=“ ZZNOTES”
	2285	D SETUP^XQ ALERT
	2286
	2287	Figure 6: Alerts—Che cking that the alert was sent
	2288	>D Q^DI
	2289
	2290	Select OPT ION: INQ < Enter> UIR E TO FILE ENTRIES
	2291
	2292	OUTPUT FRO M WHAT FIL E: ALERT
	2293	Select ALE RT RECIPIE NT: `14 <E nter> XUUS ER,14
	2294	ANOTHER ON E: <Enter>
	2295	STANDARD C APTIONED O UTPUT? YES // <Enter>
	2296	Include CO MPUTED fie lds: (N/Y /R/B): NO/ / <Enter> - No recor d number ( IEN), no C omputed Fi elds
	2297
	2298	RECIPIENT: XUUSER,15
	2299	ALERT DATE /TIME: DEC 01, 1994@ 08:02:21
	2300	ALERT ID: NO-ID;161; 2941201.08 0221
	2301	MESSAGE TEXT: Ente r Progress Note NEW ALERT FLAG: NEW
	2302	ACTION F LAG: RUN R OUTINE ENTRY POIN T: ZZOPT
	2303
	2304	Package Id entifier v s. Alert I dentifier
	2305	Package Id entifier
	2306	The softwa re applica tion ident ifier for an alert i s defined as the ori ginal valu e of the X QAID input variable when the a lert is cr eated via the SETUP^ XQALERT: S end Alerts API. Typi cally, the software applicatio n identifi er should begin with the softw are applic ation name space.
	2307	Alert Iden tifier
	2308	The alert identifier consists of three s emicolon p ieces:
	2309	pkgid_”;”_ duz_”;”_ti me
	2310	Where pkgi d is the o riginal so ftware app lication i dentifier, duz is th e DUZ of t he user wh o created the alert, and time is the tim e the aler t was crea ted (in VA FileMan f ormat). Th e alert id entifier u niquely id entifies a particula r alert (i t is used as the val ue of the .01 field in the ALE RT TRACKIN G file [#8 992.1]).
	2311	The distin ction betw een softwa re applica tion ident ifier and alert iden tifier is important. More than one alert can share the same software a pplication identifie r, but the alert ide ntifier is unique. S ome Alert Handler AP Is ask for a softwar e applicat ion identi fier (and act on mul tiple aler ts), while other API s ask for an alert i dentifier (and act o n a single alert).
	2312	Package Id entifier C onventions
	2313	The Comput erized Pat ient Recor d System ( CPRS) soft ware uses a conventi on for the format of the softw are applic ation iden tifier con sisting of three com ma-delimit ed pieces:
	2314	namespace_ “,”_dfn_“, ”_notifica tioncode
	2315	Where name space is t he softwar e applicat ion namesp ace, DFN i s the inte rnal entry number of the patie nt whom th e alert co ncerns in the PATIEN T file (#2 ), and not ification code is a code maint ained by t he CPRS so ftware des cribing th e type of alert.
	2316	NOTE: This three-com ma-piece s oftware ap plication identifier is still only the f irst semic olon piece of an ale rt identif ier.
	2317	Several Al ert Handle r APIs mak e use of t hese softw are applic ation iden tifier con ventions:
	2318	PATIENT^XQ ALERT retu rns an arr ay of aler ts for a p articular patient, b ased on th e second c omma-piece of alerts ’ software applicati on identif iers.
	2319	PTPURG^XQA LBUTL purg es alerts for a part icular pat ient, base d on the s econd comm a-piece of alerts’ s oftware ap plication identifier s.
	2320	NOTIPURG^X QALBUTL pu rges alert s with a p articular notificati on code, b ased on th e third co mma-piece of alerts’ software applicatio n identifi ers.
	2321	Glossary o f Terms fo r Alerts
	2322
	2323	Table 2: A lerts—Rela ted terms and defini tions
	2324	Term
	2325	Definition
	2326	ALERTS
	2327	An alert n otifies on e or more users of a matter re quiring im mediate at tention. A lerts func tion as br ief notice s that are distinct from mail messages o r triggere d bulletin s.Alerts a re designe d to provi de interac tive notif ication of pending c omputing a ctivities (e.g., the need to r eorder sup plies or r eview a pa tient’s cl inical tes t results) . Along wi th the ale rt message is an ind ication th at the Vie w Alerts c ommon opti on should be chosen to take fu rther acti on.An aler t includes any speci fications made by th e develope r when des igning the alert. Th is minimal ly include s the aler t message and the li st of reci pients (an informati on-only al ert). It c an also in clude an a lert actio n, softwar e applicat ion identi fier, aler t flag, an d alert da ta. Alerts are store d in the A LERT file (#8992).
	2328	ALERT ACTI ON
	2329	The comput ing activi ty that ca n be assoc iated with an alert (i.e., an option [XQ AOPT input variable] or routin e [XQAROU input vari able]).
	2330	ALERT DATA
	2331	An optiona l string t hat the de veloper ca n define w hen creati ng the ale rt. This s tring is r estored in the XQADA TA input v ariable wh en the ale rt action is taken.
	2332	ALERT FLAG
	2333	An optiona l tool cur rently con trolled by the Alert Handler t o indicate how the a lert shoul d be proce ssed (XQAF LG input v ariable).
	2334	ALERT HAND LER
	2335	The name o f the mech anism by w hich alert s are stor ed, presen ted to the user, pro cessed, an d deleted. The Alert Handler i s a part o f Kernel, in the XQA L namespac e.
	2336	ALERT IDEN TIFIER
	2337	A three-se micolon pi ece identi fier; comp osed of th e original Package I dentifier (described below) as the first piece; th e DUZ of t he alert c reator as the second piece; an d the date and time (in VA Fil eMan forma t) when th e alert wa s created as the thi rd piece. The Alert Identifier is create d by the A lert Handl er and uni quely iden tifies an alert.
	2338	ALERT MESS AGE
	2339	One line o f text tha t is displ ayed to th e user (th e XQAMSG i nput varia ble).
	2340	PACKAGE ID ENTIFIER
	2341	An optiona l identifi er that th e develope r can use to identif y the aler t for such purposes as subsequ ent lookup and delet ion (XQAID input var iable).
	2342	PURGE INDI CATOR
	2343	Checked by the Alert Handler ( in the XQA KILL input variable) to determ ine whethe r an alert should be deleted, and whethe r deletion should be for the c urrent use r or for a ll users w ho might r eceive the alert.
	2344
	2345	Applicatio n Programm ing Interf ace (API)
	2346	Several AP Is are ava ilable for developer s to work with alert s. These A PIs are de scribed be low.
	2347	AHISTORY^X QALBUTL(): Get Alert Tracking File Infor mation
	2348	Reference Type:Suppo rted
	2349	Category:A lerts
	2350	ICR #:2788
	2351	Descriptio n:This API returns i nformation from the ALERT TRAC KING file (#8992.1) for alerts with the xqaid inpu t paramete r as its a lert ID. T he data is returned descendent from the closed roo t passed i n the root input par ameter. Us ually, xqa id is know n based on alert pro cessing.
	2352	Format:AHI STORY^XQAL BUTL(xqaid ,root)
	2353	Input Para meters:xqa id:(requir ed) This i s the valu e of the a lert ident ifier. It is passed to the rou tine or op tion that is run whe n the aler t is selec ted. It ca n also be obtained f rom a list ing of all of the xq aid values for a spe cified use r and/or p atient.
	2354	root:(requ ired) This parameter is a clos ed referen ce to a lo cal or glo bal root. The inform ation asso ciated wit h the desi red entry in the ALE RT TRACKIN G file (#8 992.1) is returned d escendent from the s pecified r oot.
	2355	NOTE: A mo re user (d eveloper) friendly c all would be the ALE RTDAT^XQAL BUTL(): Ge t Alert Tr acking Fil e Informat ion API, w hich retur ns the dat a in an ar ray with t he field n umbers and names as the subscr ipts and t he interna l and exte rnal (if d ifferent) values as the value.
	2356	Output:ret urns:The d ata return ed reflect s the glob al structu re of the ALERT TRAC KING file (#8992.1).
	2357
	2358	Example
	2359	The follow ing exampl e illustra tes the us e of this API and th e format o f the data returned.
	2360	Figure 7: AHISTORY^X QALBUTL AP I—Example: Sample us e and form at of data returned
	2361	>S XQAID=“ NO-ID;20;2 990212.112 94719”
	2362
	2363	>D AHISTOR Y^XQALBUTL (XQAID,“XX XROOT”)
	2364
	2365	>ZW XXXROO T
	2366
	2367	XXXROOT(0) =NO-ID;20; 2990212.11 294719^299 0212.11294 7^NO-ID^^2 0
	2368	XXXROOT(1) =TEST MESS AGE (ROUTI NE) 20^^^X M
	2369	XXXROOT(20 ,0)=^8992. 11^20^1
	2370	XXXROOT(20 ,1,0)=20^2 990212.112 954^299021 2.145609^2 990212.145 621^299021 2.145621
	2371	XXXROOT(20 ,“B”,20,1) =
	2372
	2373	This is in the basic structure of the no des taken from the g lobal for this entry , which ca n be seen from a glo bal map vi ew of the ALERT TRAC KING file (#8992.1):
	2374	Figure 8: AHISTORY^X QALBUTL AP I—Example: Basic str ucture of the nodes taken from the globa l for this entry as seen via a global ma p view of the ALERT TRACKING f ile (#8992 .1)
	2375	^XTV(8992. 1,D0,0)= ( #.01) NAME [1F] ^ (# .02) DATE CREATED [2 D]^ (#.03) PKG
	2376	==>ID [3F] ^ (# .04) PATIE NT [4P] ^ (#.05)
	2377	GENERATED BY [5P] ^
	2378	==>(# .06) GENER ATED WHILE QUEUED [6 S] ^ (#.07 )
	2379	STATUS [7S ] ^
	2380	==>(# .08) RETEN TION DATE [8D] ^
	2381
	2382	^XTV(8992. 1,D0,1)= ( #1.01) DIS PLAY TEXT [1F] ^ (#1 .02) OPTIO N FOR PROC ESSING
	2383	==>[2 F] ^ (#1.0 3) ROUTINE TAG [3F] ^ (#1.04)
	2384	ROUTINE FO R
	2385	==>PR OCESSING [ 4F] ^
	2386
	2387	^XTV(8992. 1,D0,2)= ( #2) DATA F OR PROCESS ING [E1,24 5F] ^
	2388
	2389	^XTV(8992. 1,D0,20,0) =^8992.11P A^^ (#20) RECIPIENT
	2390
	2391	^XTV(8992. 1,D0,20,D1 ,0)= (#.01 ) RECIPIEN T [1P] ^ ( #.02) ALER T FIRST DI SPLAYED
	2392	==>[2 D] ^ (#.03 ) FIRST SE LECTED ALE RT [3D] ^ (#.04)
	2393	==>PR OCESSED AL ERT [4D] ^ (#.05) DE LETED ON [ 5D] ^
	2394	==>(# .06) AUTO DELETED [6 D] ^ (#.07 ) FORWARDE D BY [7P]
	2395	==>^ (#.08) DAT E/TIME FOR WARDED [8D ] ^ (#.09) DELETED
	2396	==>BY USER [9P] ^
	2397
	2398	NOTE: A mo re user (d eveloper) friendly A PI would b e the ALER TDAT^XQALB UTL(): Get Alert Tra cking File Informati on API, wh ich return s the data in an arr ay with th e field nu mbers and names as t he subscri pts and th e internal and exter nal (if di fferent) v alues as t he value.
	2399	ALERTDAT^X QALBUTL(): Get Alert Tracking File Infor mation
	2400	Reference Type:Suppo rted
	2401	Category:A lerts
	2402	ICR #:2788
	2403	Descriptio n:This API returns i nformation from the ALERT TRAC KING file (#8992.1) for alerts with the xqaid inpu t paramete r as its a lert ID in the array specified by the ro ot input p arameter. If root is not speci fied, then the data is returne d in an XQ ALERTD arr ay. If the specified alert is not presen t, the roo t array is returned with a NUL L value.
	2404	Format:ALE RTDAT^XQAL BUTL(xqaid [,root])
	2405	Input Para meters:xqa id:(requir ed) This i s the valu e of the a lert ident ifier. It is passed to the rou tine or op tion that is run whe n the aler t is selec ted. It ca n also be obtained f rom a list ing of all of the xq aid values for a spe cified use r and/or p atient.
	2406	root:(opti onal) This parameter is a clos ed referen ce to a lo cal or glo bal root. If root is not speci fied, then the data is returne d in an XQ ALERTD arr ay.
	2407	Output:ret urns:Retur ns:
	2408	ALERT TRAC KING File Entry—The informatio n associat ed with th e desired entry in t he ALERT T RACKING fi le (#8992. 1) descend ent from t he specifi ed root.
	2409	NULL—If th e specifie d alert is not prese nt, the ar ray root i s returned with a NU LL value.
	2410
	2411	Example
	2412	Figure 9: ALERTDAT^X QALBUTL AP I—Example
	2413	>S XQAID=“ NO-ID;20;2 990212.112 94719”
	2414
	2415	>D ALERTDA T^XQALBUTL (XQAID,$NA (^TMP($J,“ A”)))
	2416
	2417	>D ^%G Glo bal ^TMP($ J,“A”
	2418	TMP($J ,“A”
	2419	^TMP(00005 6198,“A”,. 01) = NO-I D;20;29902 12.1129471 9
	2420	^TMP(00005 6198,“A”,. 01,“NAME”) =
	2421	^TMP(00005 6198,“A”,. 02) = 2990 212.112947 ^FEB 12, 1 999@11:29: 47
	2422	^TMP(00005 6198,“A”,. 02,“DATE C REATED”) =
	2423	^TMP(00005 6198,“A”,. 03) = NO-I D ^TMP(000 056198,“A” ,.03,“PKG ID”) = ^TM P(00005619 8,“A”,.04) =
	2424	^TMP(00005 6198,“A”,. 04,“PATIEN T”) = ^TMP (000056198 ,“A”,.05) = 20^USER, XXX ^TMP(0 00056198,“ A”,.05,“GE NERATED BY ”) =
	2425	^TMP(00005 6198,“A”,. 06) = ^TMP (000056198 ,“A”,.06,“ GENERATED WHILE QUEU ED”) = ^TM P(00005619 8,“A”,.07) =
	2426	^TMP(00005 6198,“A”,. 07,“STATUS ”) =
	2427	^TMP(00005 6198,“A”,. 08) =
	2428	^TMP(00005 6198,“A”,. 08,“RETENT ION DATE”) =
	2429	^TMP(00005 6198,“A”,1 .01) = TES T MESSAGE (ROUTINE) 20
	2430	^TMP(00005 6198,“A”,1 .01,“DISPL AY TEXT”) =
	2431	^TMP(00005 6198,“A”,1 .02) = ^TM P(00005619 8,“A”,1.02 ,“OPTION F OR PROCESS ING”) = ^T MP(0000561 98,“A”,1.0 3) =
	2432	^TMP(00005 6198,“A”,1 .03,“ROUTI NE TAG”) =
	2433	^TMP(00005 6198,“A”,1 .04) = XM ^TMP(00005 6198,“A”,1 .04,“ROUTI NE FOR PRO CESSING”) = ^TMP(000 056198,“A” ,2) =
	2434	^TMP(00005 6198,“A”,2 ,“DATA FOR PROCESSIN G”) =
	2435
	2436	The data e lements at the top l evel of th e ACTIVITY TRACKING file are r eturned su bscripted by the fie ld numbers . This sub script is sufficient to obtain the data. The value s are show n as inter nal^extern al if the internal a nd externa l forms ar e differen t. The nex t subscrip t after th e field nu mber provi des the fi eld names if they ar e desired.
	2437	DELSTAT^XQ ALBUTL():G et Recipie nt Informa tion and A lert Statu s
	2438	Reference Type:Suppo rted
	2439	Category:A lerts
	2440	ICR #:3197
	2441	Descriptio n:This API obtains i nformation on the re cipients o f the most recent al ert with a specified alert ID and the st atus of wh ether the alert has been delet ed or not for those recipients .
	2442	Format:DEL STAT^XQALB UTL(xqaidv al,.values )
	2443	Input Para meters:xqa idval:(req uired) Thi s input pa rameter is a value t hat has be en used as the xqaid value for generatin g an alert by a soft ware appli cation. Th is value i dentifies the most r ecent aler t generate d with thi s xqaid va lue and th at alert g enerates t he respons es in term s of recip ients and deletion s tatus of t he alert f or each of the recip ients.
	2444	Output Par ameters:.v alues:This parameter is passed by refere nce and is returned as an arra y. The val ue of the values arr ay indicat es the num ber of ent ries in th e array. T he entries are then ordered in numerical order in the values array. Th e array co ntains the DUZ for u sers along with an i ndicator o f whether or not the alert has been dele ted.
	2445	NOTE: The contents o f the arra y are KILL ed prior t o building the list.
	2446	For exampl e:
	2447	DUZ^1—If a lert delet ed.
	2448	DUZ^0—If a lert not d eleted.
	2449	Example
	2450	>D DELSTAT ^XQALBUTL( “OR;14765; 23”,.VALUE )
	2451	The value of VALUE i ndicates t he number of entries in the ar ray. The e ntries are then orde red in num erical ord er in the VALUE arra y:
	2452	Figure 10: DELSTAT^X QALBUTL AP I—Example: Sample VA LUE array
	2453	VALUE = 3
	2454	VALUE(1) = “146^0” User 146 - not dele ted
	2455	VALUE(2) = “297^1” User 297 - deleted
	2456	VALUE(3) = “673^0” User 673 - not dele ted
	2457
	2458	NOTIPURG^X QALBUTL(): Purge Ale rts Based on Code
	2459	Reference Type:Suppo rted
	2460	Category:A lerts
	2461	ICR #:3010
	2462	Descriptio n:This API deletes a ll alerts that have the specif ied NOTIFN UM notific ation numb er as the third comm a-piece of the alert ’s Package Identifie r (the ori ginal valu e of XQAID when the alert was created).
	2463	Format:NOT IPURG^XQAL BUTL(notif num)
	2464	Input Para meters:not ifnum:(req uired) The notificat ion number for which all alert s should b e deleted. Alerts ar e deleted if the val ue of this parameter matches t he third c omma-piece in the al ert’s Pack age Identi fier.
	2465	Output:non e.
	2466
	2467	$$PENDING^ XQALBUTL() : Pending Alerts for a User
	2468	Reference Type:Suppo rted
	2469	Category:A lerts
	2470	ICR #:2788
	2471	Descriptio n:This ext rinsic fun ction retu rns whethe r or not t he user sp ecified ha s the aler t indicate d by the x qaid input parameter as pendin g. It retu rns either of the fo llowing:
	2472	1—YES, ale rt is pend ing.
	2473	0—NO, aler t is not p ending.
	2474	Format:$$P ENDING^XQA LBUTL(xqau ser,xqaid)
	2475	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN, DUZ value) in the NEW PE RSON file (#200) for the desir ed user.
	2476	xqaid:(req uired) Thi s is the v alue of th e alert id entifier. It is pass ed to the routine or option th at is run when the a lert is se lected. It can also be obtaine d from a l isting of all of the xqaid val ues for a specified user and/o r patient.
	2477	Output:ret urns:Retur ns:
	2478	1—YES, ale rt is pend ing.
	2479	0—NO, aler t is not p ending.
	2480
	2481	Examples
	2482	Example 1
	2483	The follow ing is an example of an alert not pendin g:
	2484	>S XQAID=“ NO-ID;20;2 990212.112 94719”
	2485
	2486	>W $$PENDI NG^XQALBUT L(20,XQAID )
	2487	0
	2488
	2489	Example 2
	2490	The follow ing is an example of an alert pending:
	2491	>S XQAID=“ NO-ID;20;2 990212.155 40723”
	2492
	2493	>W $$PENDI NG^XQALBUT L(20,XQAID )
	2494	1
	2495
	2496	$$PKGPEND^ XQALBUTL() : Pending Alerts for a User in Specified Software
	2497	Reference Type:Suppo rted
	2498	Category:A lerts
	2499	ICR #:2788
	2500	Descriptio n:This ext rinsic fun ction retu rns whethe r or not t he user sp ecified ha s an alert with XQAI D containi ng the fir st “;”-pie ce (softwa re/package identifie r) indicat ed by the xqkg input parameter pending. It returns either of the follo wing:
	2501	1—YES, ind icates one or more a lerts pend ing for th e specifie d user con taining th e software /package i dentifier.
	2502	0—NO, aler ts not pen ding.
	2503	Format:$$P ENDING^XQA LBUTL(xqau ser,xqkg)
	2504	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN, DUZ value) in the NEW PE RSON file (#200) for the desir ed user.
	2505	xqkg: (req uired) Thi s is the s oftware/pa ckage iden tifier por tion of th e alert id entifier ( XQAID). It is a text ual identi fier for t he softwar e that cre ated the a lert and i s the firs t “;”-piec e of XQAID . It can b e used in this conte xt to dete rmine whet her the us er specifi ed by xqau ser has an y alerts p ending con taining th e specifie d software identifie r. The sof tware iden tifier use d can be a complete software i dentifier (e.g., XU- TSK) or mo re general (e.g., XU ) to find users with any XU so ftware ale rts.
	2506	Output:ret urns:Retur ns:
	2507	1—YES, ind icates one or more a lerts pend ing for th e specifie d user con taining th e software /package i dentifier string in the packag e part of XQAID.
	2508	0—NO, aler ts not pen ding.
	2509
	2510	Examples
	2511	Example 1
	2512	The follow ing is an example of an alert not pendin g:
	2513	>S XQKG=“X U”
	2514
	2515	>W $$PKGPE ND^XQALBUT L(20,XQKG)
	2516	0
	2517
	2518	Example 2
	2519	The follow ing is an example of an alert pending (o ne or more ):
	2520	>S XQKG=“X U”
	2521
	2522	>W $$PKGPE ND^XQALBUT L(20,XQKG)
	2523	1
	2524
	2525	PTPURG^XQA LBUTL(): P urge Alert s Based on Patient
	2526	Reference Type:Suppo rted
	2527	Category:A lerts
	2528	ICR #:3010
	2529	Descriptio n:This API deletes a ll alerts that have the specif ied patien t internal entry num ber (DFN) as the sec ond comma- piece of t he alert’s Package I dentifier (the origi nal value of XQAID w hen the al ert was cr eated).
	2530	Format:PTP URG^XQALBU TL(dfn)
	2531	Input Para meters:dfn :(required ) Internal entry num ber (DFN i n the PATI ENT file [ #2]) for w hich alert s are dele ted.
	2532	Output:non e.
	2533
	2534	RECIPURG^X QALBUTL(): Purge Use r Alerts
	2535	Reference Type:Suppo rted
	2536	Category:A lerts
	2537	ICR #:3010
	2538	Descriptio n:This API deletes a ll alerts that have been sent to the use r in the N EW PERSON file (#200 ), as indi cated by t he duz par ameter.
	2539	Format:REC IPURG^XQAL BUTL(duz)
	2540	Input Para meters:duz :(required ) Internal Entry Num ber (IEN i n the NEW PERSON fil e [#200]) of the use r who rece ived alert s is delet ed.
	2541	Output:non e.
	2542
	2543	USERDATA^X QALBUTL(): Get User Informatio n for an A lert
	2544	Reference Type:Suppo rted
	2545	Category:A lerts
	2546	ICR #:2788
	2547	Descriptio n:This API returns r ecipients of the ale rt with th e xqaid in put parame ter as its alert ID from the A LERT TRACK ING file ( #8992.1) i n the arra y specifie d by the r oot input parameter. If root i s not spec ified, the n the data is return ed in the XQALUSER a rray. If t he specifi ed alert i s not pres ent, the r oot array is returne d with a N ULL value.
	2548	Format:USE RDATA^XQAL BUTL(xqaid ,xqauser,r oot)
	2549	Input Para meters:xqa id:(requir ed) This i s the valu e of the a lert ident ifier. It is passed to the rou tine or op tion that is run whe n the aler t is selec ted. It ca n also be obtained f rom a list ing of all of the xq aid values for a spe cified use r and/or p atient.
	2550	xqauser:(r equired) T his is the Internal Entry Numb er (IEN, D UZ value) in the NEW PERSON fi le (#200) for the de sired user .
	2551	root:(opti onal) This parameter is a clos ed referen ce to a lo cal or glo bal root. If root is not speci fied, then the data is returne d in the X QALUSER ar ray.
	2552	Output:ret urns:Retur ns:
	2553	ALERT TRAC KING File Entry—The informatio n associat ed with th e desired entry in t he ALERT T RACKING fi le (#8992. 1) descend ent from t he specifi ed root.
	2554	NULL—If th e specifie d alert is not prese nt, the ar ray root i s returned with a NU LL value.
	2555
	2556	Example
	2557	Figure 11: USERDATA^ XQALBUTL A PI—Example
	2558	>D USERDAT A^XQALBUTL (XQAID,20, ”XXX”)
	2559
	2560	>ZW XXX
	2561
	2562	XXX(.01)=2 0^USER,XXX XXX(.01,“ RECIPIENT” )=
	2563	XXX(.02)=2 990212.112 954^FEB 12 , 1999@11: 29:54 XXX( .02,“ALERT FIRST DIS PLAYED”)=
	2564	XXX(.03)=2 990212.145 609^FEB 12 , 1999@14: 56:09 XXX( .03,“FIRST SELECTED ALERT”)=
	2565	XXX(.04)=2 990212.145 621^FEB 12 , 1999@14: 56:21 XXX( .04,“PROCE SSED ALERT ”)=
	2566	XXX(.05)=2 990212.145 621^FEB 12 , 1999@14: 56:21 XXX( .05,“DELET ED ON”)=
	2567	XXX(.06)= XXX(.06,“A UTODELETED ”)=
	2568	XXX(.07)= XXX(.07,“F ORWARDED B Y”)=
	2569	XXX(.08)= XXX(.08,“D ATE/TIME F ORWARDED”) =
	2570	XXX(.09)= XXX(.09,“D ELETED BY USER”)=
	2571
	2572	USERLIST^X QALBUTL(): Get Recip ient Infor mation for an Alert
	2573	Reference Type:Suppo rted
	2574	Category:A lerts
	2575	ICR #:2788
	2576	Descriptio n:This API returns r ecipients of the ale rt with th e xqaid in put parame ter as its alert ID from the A LERT TRACK ING file ( #8992.1) i n the arra y specifie d by the r oot input parameter. If root i s not spec ified, the n the data is return ed in the XQALUSRS a rray. If t he specifi ed alert i s not pres ent, the r oot array is returne d with a N ULL value.
	2577	Format:USE RLIST^XQAL BUTL(xqaid ,root)
	2578	Input Para meters:xqa id:(requir ed) This i s the valu e of the a lert ident ifier. It is passed to the rou tine or op tion that is run whe n the aler t is selec ted. It ca n also be obtained f rom a list ing of all of the xq aid values for a spe cified use r and/or p atient.
	2579	root:(opti onal) This parameter is a clos ed referen ce to a lo cal or glo bal root. If root is not speci fied, then the data is returne d in the X QALUSRS ar ray.
	2580	Output:ret urns:Retur ns:
	2581	ALERT TRAC KING File Entry—The informatio n associat ed with th e desired entry in t he ALERT T RACKING fi le (#8992. 1) descend ent from t he specifi ed root.
	2582	NULL—If th e specifie d alert is not prese nt, the ar ray root i s returned with a NU LL value.
	2583
	2584	Example
	2585	>D USERLIS T^XQALBUTL (XQAID)
	2586
	2587	>ZW XQALUS RS XQALUSR S(1)=20^US ER,XXX
	2588
	2589	ACTION^XQA LERT(): Pr ocess an A lert
	2590	Reference Type:Suppo rted
	2591	Category:A lerts
	2592	ICR #:1008 1
	2593	Descriptio n:This API processes an alert for a user , if that user is th e current user. Proc essing of the alert happens ex actly as i f the user had chose n to proce ss the ale rt from th e View Ale rts menu.
	2594	Format:ACT ION^XQALER T(alertid)
	2595	Input Para meters:ale rtid:(requ ired) Aler t Identifi er of the alert to p rocess (sa me as ALER T ID field in ALERT file [#899 2]). This contains t hree semic olon-delim ited piece s, the fir st being t he origina l software applicati on identif ier, the s econd bein g the DUZ of the ale rt creator , and the third bein g the VA F ileMan dat e and time the alert was creat ed.
	2596	Output:non e.
	2597
	2598	DELETE^XQA LERT: Clea r Obsolete Alerts
	2599	Reference Type:Suppo rted
	2600	Category:A lerts
	2601	ICR #:1008 1
	2602	Descriptio n:This API deletes ( clears) a single ale rt, for th e current user (XQAK ILL=1) or all recipi ents (XQAK ILL=0 or X QAKILL und efined). T he current user (as identified by the va lue of DUZ ) does not need to b e a recipi ent of an alert; how ever, in t hat case, only a val ue of zero (0 or und efined) fo r XQAKILL makes sens e.
	2603	DELETE^XQA LERT, unli ke DELETEA ^XQALERT, deletes on ly a singl e alert wh ose alert identifier matches t he complet e Alert Id entifier.
	2604	REF: For m ore inform ation on a lert ident ifiers, se e the “Pac kage Ident ifier vs. Alert Iden tifier” se ction in t his sectio n.
	2605	Format:DEL ETE^XQALER T
	2606	Make sure to perform the follo wing steps before ca lling this API:
	2607	NEW all no n-namespac ed variabl es.
	2608	Set all in put variab les.
	2609	Call the A PI.
	2610	Input Vari ables:XQAI D:(require d) Alert I dentifier of the ale rt to dele te. It mus t be a com plete Aler t Identifi er, contai ning all t hree semic olon piece s:
	2611	The first semicolon piece (Pac kage Ident ifier) mus t be in th e same for m as the a lert creat or defined it.
	2612	The second piece bei ng the DUZ of the us er who cre ated the a lert.
	2613	The third piece bein g the time the alert was creat ed.
	2614	NOTE: The second and third pie ces are de fined by t he Alert H andler.
	2615	XQAKILL:(o ptional) X QAKILL det ermines ho w the aler t is delet ed. If XQA KILL is un defined or zero (0), the Alert Handler d eletes the alert for all recip ients. If XQAKILL is set to 1, Alert Han dler only purges the alert for the curre nt user, a s identifi ed by DUZ (using a v alue of 1 only makes sense if the curren t user is a recipien t of the a lert, howe ver).
	2616	If the sof tware appl ication id entifier p ortion of the alert identifier is “NO-ID ”, however , the aler t is treat ed as if X QAKILL wer e set to 1 (i.e., th e alert is deleted o nly from o ne user), regardless of how it is actual ly set.
	2617	Output:non e.
	2618
	2619	DELETEA^XQ ALERT: Cle ar Obsolet e Alerts
	2620	Reference Type:Suppo rted
	2621	Category:A lerts
	2622	ICR #:1008 1
	2623	Descriptio n:This API deletes ( clears) al l alerts w ith the sa me softwar e applicat ion identi fier, for the curren t user (XQ AKILL=1) o r all reci pients (XQ AKILL=0 or XQAKILL u ndefined). The curre nt user (a s identifi ed by the value of D UZ) does n ot need to be a reci pient of a n alert; h owever, in that case , only a v alue of ze ro (0 or u ndefined) for XQAKIL L makes se nse.
	2624	One exampl e of the u se of DELE TEA^XQALER T is when a troubles ome condit ion has be en resolve d. You can use this API to del ete any un processed alerts ass ociated wi th the con dition. It deletes a ll alerts whose soft ware appli cation ide ntifiers m atch the s oftware ap plication identifier you pass in the xqa id input p arameter ( multiple a lerts can potentiall y share th e same sof tware appl ication id entifier).
	2625	REF: For m ore inform ation on s oftware ap plication identifier s, see the “Package Identifier vs. Alert Identifie r” section in this s ection.
	2626	Format:DEL ETEA^XQALE RT
	2627	Make sure to perform the follo wing steps before ca lling this API:
	2628	NEW all no n-namespac ed variabl es.
	2629	Set all in put variab les.
	2630	Call the A PI.
	2631	Input Vari ables:XQAI D:(require d) All ale rts whose software a pplication identifie r matches the value of this in put parame ter is del eted, for the alert recipients designate d by the x qakill inp ut paramet er.
	2632	The form o f XQAID ca n be exact ly as init ially set when creat ing the al ert. Alter natively, it can con tain the t wo additio nal semico lon pieces added by the Alert Handler (t he full al ert identi fier). The two addit ional semi colon piec es are ign ored, howe ver; this API only r equires th e original software applicatio n identifi er.
	2633	If the ale rt identif ier you sp ecify is “ NO-ID”, ho wever, (th e generic software a pplication ID assign ed to aler ts with no original software a pplication identifie r), this A PI does no t delete m atching al erts.
	2634	XQAKILL:(o ptional) X QAKILL det ermines ho w the aler t is delet ed. If XQA KILL is un defined or zero (0), the Alert Handler d eletes mat ching aler ts for all recipient s. If XQAK ILL is set to 1, Ale rt Handler deletes m atching al erts for t he current user, as identified by DUZ (u sing a val ue of 1 on ly makes s ense if th e current user is al so a recip ient of th e alert, h owever).
	2635	Output:non e.
	2636
	2637	GETACT^XQA LERT(): Re turn Alert Variables
	2638	Reference Type:Suppo rted
	2639	Category:A lerts
	2640	ICR #:1008 1
	2641	Descriptio n:This API returns t o the call ing routin e the requ ired varia bles to ac t on a spe cific aler t.
	2642	Format:GET ACT^XQALER T(alertid)
	2643	Make sure to perform the follo wing steps before ca lling this API:
	2644	NEW all no n-namespac ed variabl es.
	2645	Set all in put variab les.
	2646	Call the A PI.
	2647	Input Para meters:ale rtid:(requ ired) This is the al ert identi fier in th e ALERT TR ACKING fil e (#8992.1 ).
	2648	Output Var iables:XQA ID:This is the full alert iden tifier.
	2649	XQADATA:Th e XQADATA variable s tores any software a pplication -specific data strin g that was passed at the time the alert was genera ted.
	2650	XQAOPT:Ind icates a n on-menu ty pe option on the use r’s primar y, seconda ry or comm on menu to be run if not null.
	2651	XQAROU:Ind icates the routine o r tag^rout ine to run when the alert is p rocessed. It can hav e three va lues:
	2652	Null—A nul l value in dicates no routine t o be used (XQAOPT co ntains opt ion name t o be run).
	2653	^<space>—A value of ^<space> i ndicates t hat the al ert is inf ormation o nly (no ro utine or o ption acti on involve d).
	2654	^ROUTINE o r TAG^ROUT INE—The na me of the routine as ^ROUTINE or TAG^ROU TINE.
	2655
	2656	PATIENT^XQ ALERT(): G et Alerts for a Pati ent
	2657	Reference Type:Suppo rted
	2658	Category:A lerts
	2659	ICR #:1008 1
	2660	Descriptio n:This API allows yo u to retur n an array of all al erts for a particula r patient that are e ither:
	2661	Open.
	2662	Within a g iven time range (bot h open and closed).
	2663	The associ ation of a n alert wi th a patie nt is base d on the c onventions used by t he CPRS so ftware app lication f or the Pac kage Ident ifier (ori ginal valu e of XQAID input var iable when creating the alert) , where th e second c omma-piece is a poin ter to the PATIENT f ile (#2).
	2664	REF: For i nformation on CPRS c onventions for the f ormat of t he Package Identifie r, see the “Package Identifier vs. Alert Identifie r” section in this s ection.
	2665	Format:PAT IENT^XQALE RT(root,df n[,startda te][,endda te])
	2666	Input Para meters:roo t:(require d) Fully r esolved gl obal or lo cal refere nce in whi ch to retu rn a list of matchin g alerts.
	2667	dfn:(requi red) Inter nal entry number (DF N in the P ATIENT fil e [#2]) of the patie nt for who m alerts a re returne d.
	2668	startdate: (optional) Starting date to ch eck for al erts. If y ou pass th is paramet er, all al erts are r eturned, o pen or clo sed, from the startd ate until the enddat e (if no e nddate is specified, all alert s beyond t he startda te are ret urned). If you omit this param eter (and enddate), only curre ntly open alerts are returned.
	2669	enddate:(o ptional) E nding date to check for alerts . If you o mit this p arameter, but pass a startdate , all aler ts are ret urned beyo nd the sta rtdate.
	2670	Output Par ameters:ro ot:All ale rts matchi ng the req uest are r eturned in the input parameter you speci fied in ro ot, in the following format:
	2671	root=numbe r of match ing alerts
	2672	root(1)= “ I “_mess agetext_”^ ”_alertid
	2673	root(2)=.. .
	2674	Where the first thre e characte rs are eit her:
	2675	“I “: i f the aler t is infor mational
	2676	“ “: i f the aler t runs a r outine
	2677	In additio n, where a lertid (Al ert Identi fier) cont ains three semicolon -delimited pieces:
	2678	The origin al softwar e applicat ion identi fier (valu e of XQAID ).
	2679	The DUZ of the alert creator.
	2680	The VA Fil eMan date and time t he alert w as created .
	2681	SETUP^XQAL ERT: Send Alerts
	2682	Reference Type:Suppo rted
	2683	Category:A lerts
	2684	ICR #:1008 1
	2685	Descriptio n:This API sends ale rts to use rs; howeve r, the pre ferred API to use is $$SETUP1^ XQALERT: S end Alerts .
	2686	To send an informati on-only al ert, make sure that XQAOPT and XQAROU in put variab les are no t defined. To send a n alert th at takes a n action, specify ei ther the X QAOPT (to run an opt ion) or XQ AROU (to r un a routi ne) input variables.
	2687	Format:SET UP^XQALERT
	2688	Make sure to perform the follo wing steps before ca lling this API:
	2689	NEW all no n-namespac ed variabl es.
	2690	Set all in put variab les.
	2691	Call the A PI.
	2692	Input Vari ables:XQA: (required) Array def ining at l east one u ser to rec eive the a lert. Subs cript the array with users’ DU Z numbers to send to individua l users; s ubscript t he array w ith mail g roup names to send t o users in mail grou ps:
	2693	>S XQA(USE RDUZ)=“”
	2694	>S XQA(“G. MAILGROUP” )=“”
	2695	XQAARCH:(o ptional) N umber of d ays that a lert track ing inform ation for this alert should be retained in the ALE RT TRACKIN G file (#8 992.1). De fault time period is 30 days. Users can specify a different number of days using this inpu t variable . To retai n informat ion foreve r, a value of 100000 is recomm ended (goo d for prox imately 22 0 years).
	2696	XQACNDEL:( optional) Setting a value in t he XQACNDE L variable prior to calling th is API cau ses the CA N DELETE W ITHOUT PRO CESSING fi eld (#.1) in the ALE RT file (# 8992) to b e set. A v alue in th is field i ndicates t hat the al ert can be deleted b y the user without h aving proc essed it.
	2697	XQADATA:(o ptional) U se this to store a s oftware ap plication- specific d ata string , in any f ormat. It is restore d in the X QADATA inp ut variabl e when the user proc esses the alert, and is theref ore, avail able to th e routine or option that proce sses the a lert.
	2698	You can us e any deli miter in t he input v ariable, i ncluding t he caret. You can us e it to ma ke data su ch as pati ent number , lab acce ssion, or cost cente r availabl e to your software a pplication -specific routine or option wi thout need ing to que ry the use r when the y process the alert. It is up to your ro utine or o ption to k now what f ormat is u sed for da ta in this string.
	2699	XQAFLG:(op tional) Al ert flag t o regulate processin g (current ly not sup ported). T he values are:
	2700	D—To delet e an infor mation-onl y alert af ter it has been proc essed (the default f or informa tion-only alerts).
	2701	R—To run t he alert a ction imme diately up on invocat ion (the d efault for alerts th at have as sociated a lert actio ns).
	2702	This input variable currently has no eff ect, howev er.
	2703	XQAGUID:(o ptional) A s of Kerne l patch XU 8.0207, the GUID F OR GUI add s an inter face GUID (a 32-char acter stri ng contain ing hexade cimal digi ts in a sp ecific for mat within curly bra ces) to pe rmit a pro gram on th e client t o process the alert. The prese nce of a G UID in the variable indicates that the a lert can b e processe d within a GUI envir onment, an d opens th e correct applicatio n to proce ss the ale rt within the GUI en vironment.
	2704	NOTE: This functiona lity has n ever been implemente d by CPRS or other G UI applica tions.
	2705	XQAID:(opt ional) Pac kage ident ifier for the alert, typically a softwar e applicat ion namesp ace follow ed by a sh ort charac ter string . Must not contain c arets (“^” ) or semic olons (“;” ). If you do not set XQAID, yo u are not able to id entify the alert in the future , either d uring aler t processi ng, to del ete the al ert, or to perform o ther actio ns with th e alert.
	2706	REF: For i nformation on CPRS c onventions for the f ormat of t he Package Identifie r, see the “Package Identifier vs. Alert Identifie r” section .
	2707	XQAMSG:(re quired) Co ntains the text of t he alert. 80 charact ers can be displayed in the or iginal ale rt. 70 cha racters ca n be displ ayed in th e View Ale rt listing . The stri ng cannot contain a caret (“^” ).
	2708	XQAOPT:(op tional) Na me of a no n-menu typ e option o n the user ’s primary , secondar y or commo n menu. Th e phantom jump navig ates to th e destinat ion option , checking pathway r estriction s in so do ing. An er ror result s if the s pecified o ption is n ot in the user’s men u pathway.
	2709	XQAROU:(op tional) In dicates a routine or tag^routi ne to run when the a lert is pr ocessed. I f both XQA OPT and XQ AROU are d efined, XQ AOPT is us ed and XQA ROU is ign ored.
	2710	XQASUPV:(o ptional) N umber of d ays to wai t before D elete Old (>14d) Ale rts option forwards alert to r ecipient’s superviso r based on Service/S ection, if alert is unprocesse d by recip ient. Can be a numbe r from 1 t o 30.
	2711	XQASURO:(o ptional) N umber of d ays to wai t before D elete Old (>14d) Ale rts option forwards alert to r ecipient’s MailMan s urrogates (if any), if alert i s unproces sed by rec ipient. Ca n be a num ber from 1 to 30.
	2712	XQATEXT:(o ptional) A s of Kerne l patch XU 8.0207, this varia ble permit s informat ional text of any le ngth to be passed wi th an aler t. When th e alert is selected, the conte nts of thi s variable is displa yed in a S creenMan f orm within the roll and scroll environme nt.
	2713	NOTE: It w as also in tended to be display ed within a text dis play box w ithin the GUI enviro nment. How ever, CPRS has never implement ed this fu nctionalit y, so it c an only be viewed in the roll and scroll environme nt.
	2714	Output:non e.
	2715
	2716	Details—Wh en the Ale rt is Proc essed
	2717	Once the a lert is cr eated, the user is t hen able t o receive and proces s the aler t from the ir View Al erts listi ng. When t his occurs , Alert Ha ndler exec utes the f ollowing f our steps for the al ert:
	2718	Alert Hand ler sets u p the foll owing inpu t variable s:
	2719	XQADATA—If originall y set when alert was created.
	2720	XQAID—If o riginally set when a lert was c reated.
	2721	XQAKILL—Th e purge in dicator. I t is alway s set to 1 by the Al ert Handle r.
	2722	If you ass ociated a software a pplication identifie r, XQAID, with the a lert, it i s restored along wit h two addi tional sem icolon pie ces:
	2723	Current us er number.
	2724	Current da te/time.
	2725	With the t wo additio nal semico lon pieces , the soft ware appli cation ide ntifier be comes the alert iden tifier. If you did n ot define XQAID when creating the alert, Alert Han dler sets XQAID inpu t variable to “NO-ID ” followed by the tw o addition al semicol on pieces.
	2726	Alert Hand ler runs t he routine or any op tion speci fied in th e XQAOPT o r XQAROU i nput varia bles.
	2727	You can re fer to the three inp ut variabl es listed above (i.e ., XQADATA , XQAID, a nd XQAKILL ) in the o ption or r outine tha t processe s the aler t.
	2728	Once the r outine or option fin ishes, Ale rt Handler deletes t he alert, under the following conditions :
	2729	If XQAKILL remains a t the valu e of 1 as it was set in Step # 1 above, t he alert i s deleted for the cu rrent user only.
	2730	To prevent the alert from bein g deleted, KILL XQAK ILL during Step #2 a bove. You may not wa nt the ale rt to be d eleted if processing , such as entering a n electron ic signatu re, was no t complete d.
	2731	To delete the alert for all re cipients o f the aler t, not jus t the curr ent user, set XQAKIL L to zero (0) during Step #2 a bove. When XQAKILL i s set to 0 , Alert Ha ndler sear ches for a ny alerts with a mat ching Aler t Identifi er, all th ree semico lon pieces :
	2732	Original P ackage Ide ntifier.
	2733	Alert send er.
	2734	Date/Time the alert was sent.
	2735	It purges them so th at other u sers need not be not ified of a n obsolete alert.
	2736	NOTE: To d elete an a lert for a ll recipie nts, you m ust define XQAID wit h appropri ate specif icity when creating the alert.
	2737	Finally, t he Alert H andler cle ans up by KILLing XQ ADATA, XQA ID, and XQ AKILL. Ale rt Handler returns t he user to the View Alerts lis ting if pe nding aler ts remain. Otherwise , Alert Ha ndler retu rns the us er to thei r last men u prompt.
	2738	Example
	2739	Figure 12: SETUP^XQA LERT API—C all to sen d an alert sample
	2740	;send an a lert
	2741	;assume DF N is for p atient XUP ATIENT,ONE
	2742	N XQA,XQAA RCH,XQADAT A,XQAFLG,X QAGUID,XQA ID,XQAMSG, XQAOPT,XQA ROU,XQASUP V,XQASURO, XQATEXT,XQ ALERR
	2743	S XQA(161) =“” ; reci pient is u ser `161
	2744	S XQAMSG=“ Elevated C EA for “_$ $GET1^DIQ( 2,DFN_”,“, .01)_” (“_ $E($$GET1^ DIQ(2,DFN_ ”,“,9),6,9 )_”) Sched ule follow -up exam i n Surgical Clinic.”
	2745	D SETUP^XQ ALERT
	2746	Q
	2747
	2748	Figure 13: SETUP^XQA LERT API—R esulting a lert, from View Aler ts option
	2749	Select Sys tems Manag er Menu Op tion: “VA
	2750
	2751	1.I Elev ated CEA f or XUPATIE NT,ONE (53 45). Sche dule follo w-up exam in Surgica l Clinic.
	2752	Select fro m 1 to 1
	2753	or enter ? , A, I, P, M, R, or ^ to exit:
	2754
	2755	$$SETUP1^X QALERT: Se nd Alerts
	2756	Reference Type:Suppo rted
	2757	Category:A lerts
	2758	ICR #:1008 1
	2759	Descriptio n:This API sends ale rts to use rs. This i s the pref erred API rather tha n SETUP^XQ ALERT: Sen d Alerts.
	2760	To send an informati on-only al ert, make sure that XQAOPT and XQAROU in put variab les are no t defined. To send a n alert th at takes a n action, specify ei ther the X QAOPT (to run an opt ion) or XQ AROU (to r un a routi ne) input variables.
	2761	Format:$$S ETUP1^XQAL ERT
	2762	Make sure to perform the follo wing steps before ca lling this API:
	2763	NEW all no n-namespac ed variabl es.
	2764	Set all in put variab les.
	2765	Call the A PI.
	2766	Input Vari ables:XQA: (required) Array def ining at l east one u ser to rec eive the a lert. Subs cript the array with users’ DU Z numbers to send to individua l users; s ubscript t he array w ith mail g roup names to send t o users in mail grou ps:
	2767	>S XQA(USE RDUZ)=“”
	2768	>S XQA(“G. MAILGROUP” )=“”
	2769	XQAARCH:(o ptional) N umber of d ays that a lert track ing inform ation for this alert should be retained in the ALE RT TRACKIN G file (#8 992.1). De fault time period is 30 days. Users can specify a different number of days using this inpu t variable .
	2770	NOTE: Crit ical patie nt data, a s part of medical re cords, sho uld be ret ained for at least 6 5 years, w hich is 23 ,725 days. To retain informati on forever , a value of 100000 is recomme nded (good for about 273+ year s). Sites may not ha ve suffici ent disk s torage spa ce to acco mmodate th is need, h owever.
	2771	XQACNDEL:( optional) Setting a value in t he XQACNDE L variable prior to calling th is API cau ses the CA N DELETE W ITHOUT PRO CESSING fi eld (#.1) in the ALE RT file (# 8992) to b e set. A v alue in th is field i ndicates t hat the al ert can be deleted b y the user without h aving proc essed it.
	2772	XQADATA:(o ptional) U se this to store a s oftware ap plication- specific d ata string , in any f ormat. It is restore d in the X QADATA inp ut variabl e when the user proc esses the alert and is therefo re availab le to the routine or option th at process es the ale rt.
	2773	You can us e any deli miter in t he input v ariable, i ncluding t he caret. You can us e it to ma ke data su ch as pati ent number , lab acce ssion, or cost cente r availabl e to your software a pplication -specific routine or option wi thout need ing to que ry the use r when the y process the alert. It is up to your ro utine or o ption to k now what f ormat is u sed for da ta in this string.
	2774	XQAFLG:(op tional) Al ert flag t o regulate processin g (current ly not sup ported). T he values are:
	2775	D—To delet e an infor mation-onl y alert af ter it has been proc essed (the default f or informa tion-only alerts).
	2776	R—To run t he alert a ction imme diately up on invocat ion (the d efault for alerts th at have as sociated a lert actio ns).
	2777	This input variable currently has no eff ect, howev er.
	2778	XQAGUID:(o ptional) A s of Kerne l patch XU 8.0207, the GUID F OR GUI add s an inter face GUID (a 32 char acter stri ng contain ing hexade cimal digi ts in a sp ecific for mat within curly bra ces) to pe rmit a pro gram on th e client t o process the alert. The prese nce of a G UID in the variable indicates that the a lert can b e processe d within a GUI envir onment, an d opens th e correct applicatio n to proce ss the ale rt within the GUI en vironment.
	2779	NOTE: Curr ently, thi s function ality has not been i mplemented by CPRS o r other GU I applicat ions.
	2780	XQAID:(opt ional) Pac kage ident ifier for the alert, typically a softwar e applicat ion namesp ace follow ed by a sh ort charac ter string . Must not contain c arets (“^” ) or semic olons (“;” ). If you do not set XQAID, yo u are not able to id entify the alert in the future , either d uring aler t processi ng, to del ete the al ert, or to perform o ther actio ns with th e alert.
	2781	REF: For i nformation on CPRS c onventions for the f ormat of t he Package Identifie r, see the “Package Identifier vs. Alert Identifie r” section .
	2782	XQAMSG:(re quired) Co ntains the text of t he alert. 80 charact ers can be displayed in the or iginal ale rt. 70 cha racters ca n be displ ayed in th e View Ale rt listing . The stri ng cannot contain a caret (“^” ).
	2783	XQAOPT:(op tional) Na me of a no n-menu typ e option o n the user ’s primary , secondar y or commo n menu. Th e phantom jump navig ates to th e destinat ion option , checking pathway r estriction s in so do ing. An er ror result s if the s pecified o ption is n ot in the user’s men u pathway.
	2784	XQAREVUE:( optional) This varia ble sets t he DAYS FO R BACKUP R EVIEWER fi eld (#.15) in the AL ERTS file (#8992). I t must be an integer from 1 to 15.
	2785	XQAROU:(op tional) In dicates a routine or tag^routi ne to run when the a lert is pr ocessed. I f both XQA OPT and XQ AROU are d efined, XQ AOPT is us ed and XQA ROU is ign ored.
	2786	XQASUPV:(o ptional) S upervisor forwarding . Number o f days to wait befor e Delete O ld (>14d) Alerts opt ion forwar ds alert t o recipien t’s superv isor, if u nprocessed by recipi ent. Can b e a number from 1 to 30. Super visor is d etermined from the r ecipient’s NEW PERSO N file (#2 00) entry pointer to the SERVI CE/SECTION file (#49 ), and the n the entr y (if any) in the po inted-to S ervice/Sec tion’s CHI EF field.
	2787	XQASURO:(o ptional) N umber of d ays to wai t before D elete Old (>14d) Ale rts option forwards alert to r ecipient’s MailMan s urrogates (if any), if alert i s unproces sed by rec ipient. Ca n be a num ber from 1 to 30.
	2788	XQATEXT:(o ptional) A s of Kerne l patch XU 8.0207, this varia ble permit s informat ional text of any le ngth to be passed wi th an aler t. When th e alert is selected, the conte nts of thi s variable are displ ayed in a ScreenMan form withi n the roll and scrol l environm ent.
	2789	NOTE: It w as also in tended to be display ed within a text dis play box w ithin the GUI enviro nment. Cur rently, CP RS has not implement ed this fu nctionalit y, so it c an only be viewed in the roll and scroll environme nt.
	2790	Output:ret urns:Retur ns:
	2791	1—The aler t was sent successfu lly.
	2792	0—The aler t was not sent succe ssfully, i n which ca se the XQA LERR varia ble contai ns a text string ind icating th e reason t hat the al ert was no t sent.
	2793	Output Var iables:XQA LERR:Retur ns:
	2794	NULL—It th e alert wa s sent suc cessfully, this vari able is nu ll.
	2795	Text Strin g—If the a lert was n ot sent su ccessfully , this var iable cont ains a tex t string t hat indica tes the re ason that the alert was not se nt.
	2796
	2797	Details—Wh en the Ale rt is Proc essed
	2798	Once the a lert is cr eated, the user is t hen able t o receive and proces s the aler t from the ir View Al erts listi ng. When t his occurs , Alert Ha ndler exec utes the f ollowing f our steps for the al ert:
	2799	Alert Hand ler sets u p the foll owing inpu t variable s:
	2800	XQADATA—If originall y set when alert was created.
	2801	XQAID—If o riginally set when a lert was c reated.
	2802	XQAKILL—Th e purge in dicator. I t is alway s set to 1 by the Al ert Handle r.
	2803	If you ass ociated a software a pplication identifie r, XQAID, with the a lert, it i s restored along wit h two addi tional sem icolon pie ces:
	2804	Current us er number.
	2805	Current da te/time.
	2806	With the t wo additio nal semico lon pieces , the soft ware appli cation ide ntifier be comes the alert iden tifier. If you did n ot define XQAID when creating the alert, Alert Han dler sets XQAID inpu t variable to “NO-ID ” followed by the tw o addition al semicol on pieces.
	2807	Alert Hand ler runs t he routine or any op tion speci fied in th e XQAOPT o r XQAROU i nput varia bles.
	2808	You can re fer to the three inp ut variabl es listed above (i.e ., XQADATA , XQAID, a nd XQAKILL ) in the o ption or r outine tha t processe s the aler t.
	2809	Once the r outine or option fin ishes, Ale rt Handler deletes t he alert, under the following conditions :
	2810	If XQAKILL remains a t the valu e of 1 as it was set in Step 1 , the aler t is delet ed for the current u ser only.
	2811	To prevent the alert from bein g deleted, KILL XQAK ILL during Step 2. Y ou may not want the alert to b e deleted if process ing, such as enterin g an elect ronic sign ature, was not compl eted.
	2812	To delete the alert for all re cipients o f the aler t, not jus t the curr ent user, set XQAKIL L to zero (0) during Step #2 a bove. When XQAKILL i s set to 0 , Alert Ha ndler sear ches for a ny alerts with a mat ching Aler t Identifi er, all th ree semico lon pieces :
	2813	Original P ackage Ide ntifier.
	2814	Alert send er.
	2815	Date/Time the alert was sent.
	2816	It purges them so th at other u sers need not be not ified of a n obsolete alert.
	2817	NOTE: To d elete an a lert for a ll recipie nts, you m ust define XQAID wit h appropri ate specif icity when creating the alert.
	2818	Finally, t he Alert H andler cle ans up by KILLing XQ ADATA, XQA ID, and XQ AKILL. Ale rt Handler returns t he user to the View Alerts lis ting if pe nding aler ts remain. Otherwise , Alert Ha ndler retu rns the us er to thei r last men u prompt.
	2819	Example
	2820	Figure 14: $$SETUP1^ XQALERT AP I—Call to send an al ert sample
	2821	;send an a lert
	2822	;assume DF N is for p atient XUP ATIENT,ONE
	2823	N XQA,XQAA RCH,XQADAT A,XQAFLG,X QAGUID,XQA ID,XQAMSG, XQAOPT,XQA ROU,XQASUP V,XQASURO, XQATEXT,XQ ALERR
	2824	S XQA(161) =“” ; reci pient is u ser `161
	2825	S XQAMSG=“ Elevated C EA for ”_$ $GET1^DIQ( 2,DFN_“,”, .01)_“ (”_ $E($$GET1^ DIQ(2,DFN_ “,”,9),6,9 )_“) Sched ule follow -up exam i n Surgical Clinic.”
	2826	S VAR=$$SE TUP1^XQALE RT I ‘XQAL ERR W !,“E RROR IN AL ERT: ”,XQA LERR
	2827	Q
	2828
	2829	Figure 15: $$SETUP1^ XQALERT AP I—Resultin g alert, f rom View A lerts opti on
	2830	Select Sys tems Manag er Menu Op tion: “VA
	2831
	2832
	2833	1.I Elev ated CEA f or XUPATIE NT,ONE (53 45). Sche dule follo w-up exam in Surgica l Clinic.
	2834	Select fro m 1 to 1
	2835	or enter ? , A, I, P, M, R, or ^ to exit:
	2836
	2837	USER^XQALE RT(): Get Alerts for a User
	2838	Reference Type:Suppo rted
	2839	Category:A lerts
	2840	ICR #:1008 1
	2841	Descriptio n:This API returns a list of a lerts for a given us er. You ca n return a list of a ll alerts for a part icular use r that are either:
	2842	Open.
	2843	Within a g iven time range (ope n and clos ed).
	2844	Format:USE R^XQALERT( root[,duz] [,startdat e][,enddat e])
	2845	Input Para meters:roo t:(require d) Fully r esolved gl obal or lo cal refere nce in whi ch to retu rn a list of matchin g alerts.
	2846	duz:(optio nal) DUZ n umber of t he user fo r whom the alert lis t is retur ned. If yo u do not p ass a numb er, it use s the curr ent user’s DUZ.
	2847	startdate: (optional) Starting date to ch eck for al erts. If y ou pass th is paramet er, all al erts are r eturned, o pen or clo sed, from the startd ate until the enddat e (if no e nddate is specified, all alert s beyond t he startda te are ret urned). If you omit the startd ate parame ter (and e nddate), o nly curren tly open a lerts are returned.
	2848	enddate:(o ptional) E nding date to check for alerts . If you o mit this p arameter, but pass a startdate , all aler ts are ret urned beyo nd the sta rtdate.
	2849	Output Par ameters:ro ot:All ale rts matchi ng the req uest are r eturned in the input parameter you speci fied in ro ot, in the following format:
	2850	root=numbe r of match ing alerts
	2851	root(1)= “ I “_mess agetext_”^ ”_alertid
	2852	root(2)=.. .
	2853	Where the first thre e characte rs are eit her:
	2854	“I “: i f the aler t is infor mational
	2855	“ “: i f the aler t runs a r outine
	2856	In additio n, where a lertid (Al ert Identi fier) cont ains three semicolon -delimited pieces:
	2857	The origin al softwar e applicat ion identi fier (valu e of XQAID ).
	2858	The DUZ of the alert creator.
	2859	The VA Fil eMan date and time t he alert w as created .
	2860	Example
	2861	Figure 16: USER^XQAL ERT API—Ex ample
	2862	>D USER^XQ ALERT(“ZZA LRT”,ZZDUZ ,2900101)
	2863
	2864	>ZW ZZALRT
	2865	ZZALRT=1
	2866	ZZLART(1)= “I Test M essage^NO- ID;92;2940 729.10312”
	2867
	2868	FORWARD^XQ ALFWD(): F orward Ale rts
	2869	Reference Type:Suppo rted
	2870	Category:A lerts
	2871	ICR #:3009
	2872	Descriptio n:This API can be us ed to forw ard alerts (in most cases, for the curre nt user on ly). It is a silent (no screen input or output) AP I, and so can be use d for wind owed appli cations.
	2873	Format:FOR WARD^XQALF WD([.]aler ts,[.]user s,type[,co mment])
	2874	Input Para meters:[.] alerts:(re quired) Ar ray of ale rts to be forwarded, each iden tified by its full a lert ident ifier (the value of the ALERT ID field i n the ALER T DATE/TIM E multiple of the cu rrent user ’s entry i n the ALER T file [#8 992]). Use the $$SET UP1^XQALER T: Send Al erts API t o obtain a lert ident ifiers for a user’s current op en alerts.
	2875	If only a single ale rt is to b e forwarde d, only th e top node must be s et (set it to the al ert identi fier of th e alert to forward, and pass b y value). If there a re multipl e alerts t o forward, the value of each e ntry in th e array sh ould be on e of the d esired ale rt identif ier. For e xample:
	2876	A6AALRT(1) =“NO-ID;92 ;2941215.1 00432”
	2877	A6AALRT(2) =“NO-ID;16 1;2941220. 111907”
	2878	A6AALRT(3) =“NO-ID;16 1;2941220. 132401”
	2879	If using a n array, t he array m ust be pas sed by ref erence in the parame ter list.
	2880	[.]users:( required) Users to f orward ale rt to. For forwardin g as an al ert or as a mail mes sage (when the type parameter is A or M) , the inpu t paramete r can spec ify one or more user s, and/or mail group s. For use rs, specif y by IEN ( in the NEW PERSON fi le [#200]) . You do n ot need to precede t he user’s IEN with a n accent g rave (`). For mail g roups, spe cify in fo rmat G.MAI LGROUP.
	2881	If there i s only a s ingle user or mail g roup, just set the t op node of the array to that v alue, and pass it by value. If there are multiple values to be passed, pass them as the va lues of nu merically subscripte d array no des (and p ass the ar ray by ref erence). F or example :
	2882	A6AUSER(1) =“G.MAS CL ERKS”
	2883	A6AUSER(2) =“G.MAS OV ERNIGHT”
	2884	For forwar ding to a printer (w hen the ty pe paramet er is P), there shou ld be only a single value spec ifying the desired e ntry in th e DEVICE f ile (#3.5) . You can specify th e device e ither by n ame or by Internal E ntry Numbe r (IEN). I f specifyi ng by IEN, precede t he IEN wit h an accen t grave (e .g., `202) .
	2885	type:(requ ired) Indi cates the method of forwarding desired. The option s are the single cha racters:
	2886	“A”—Forwa rd as an A lert.
	2887	“M”—Forwar d as a Mai l Message.
	2888	“P”—Print a copy of the alert.
	2889	If the val ue passed is not A, M, or P, t hen no act ion is tak en.
	2890	comment:(o ptional) A character string to use as a comment to accompany the alert when it i s forwarde d.
	2891	Output:non e.
	2892
	2893	Example
	2894	Figure 17: FORWARD^X QALFWD API —Example
	2895	; get open alerts fo r current user
	2896	K A6AALRT D USER^XQA LERT(“A6AA LRT”)
	2897	;
	2898	I +A6AALRT D ; if a ny current alerts...
	2899	.; loop th rough A6AA LRT array, parse ale rt id for each open alert
	2900	.K A6AALRT 1 S A6ASUB =“”,A6AI=0
	2901	.F S A6AS UB=$O(A6AA LRT(A6ASUB )) Q:’$L(A 6ASUB) D
	2902	..S A6AI=A 6AI+1,A6AA LRT1(A6AI) =$P(A6AALR T(A6ASUB), “^”,2)
	2903	.;
	2904	.;forward open alert s of curre nt user to MAS CLERK S mail gro up
	2905	.K A6AUSER S A6AUSER =“G.MAS CL ERKS”
	2906	.D FORWARD ^XQALFWD(. A6AALRT1,A 6AUSER,“A” ,“Forwarde d Alert”)
	2907	Q
	2908
	2909	$$CURRSURO ^XQALSURO( ): Get Cur rent Surro gate for A lerts
	2910	Reference Type:Suppo rted
	2911	Category:A lerts
	2912	ICR #:2790
	2913	Descriptio n:This ext rinsic fun ction obta ins the cu rrent surr ogate for alerts (if any for t he user wi th DUZ spe cified by the xqause r input pa rameter.
	2914	Format:$$C URRSURO^XQ ALSURO(xqa user)
	2915	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN, DUZ value) in the NEW PE RSON file (#200) for the speci fied user with the s urrogate.
	2916	Output:ret urns:Retur ns:
	2917	DUZ—Intern al Entry N umber (IEN ) of the s urrogate.
	2918	-1—If ther e is no su rrogate sp ecified.
	2919
	2920	$$GETSURO^ XQALSURO() : Get Curr ent Surrog ate Inform ation
	2921	Reference Type:Suppo rted
	2922	Category:A lerts
	2923	ICR #:3213
	2924	Descriptio n:This ext rinsic fun ction retu rns the fo llowing st ring of in formation on the cur rent surro gate for t he user wi th XQAUSER as his or her Inter nal Entry Number (IE N) in the NEW PERSON file (#20 0):
	2925	ien^NAME^F M_STARTDAT E^FM_ENDDA TE
	2926	If there i s no surro gate, the result is:
	2927	^^^
	2928	If either of the sta rt or end dates and times is n ot specifi ed, a null value is returned f or that pi ece of the return st ring.
	2929	REF: For a descripti on of each piece of informatio n separate d by the c aret (“^”) , see the “Output” s ection bel ow.
	2930	Format:$$G ETSURO^XQA LSURO(xqau ser)
	2931	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN) in t he NEW PER SON file ( #200) of t he user fo r whom the alert sur rogate inf ormation i s to be re turned.
	2932	Output:ret urns:Retur ns the fol lowing str ing of inf ormation, each piece separated by a care t (“^”):
	2933	IEN^NAME^F M_STARTDAT E^FM_ENDDA TE
	2934	IEN—Intern al Entry N umber (IEN ) of the S URROGATE i n the NEW PERSON fil e (#200).
	2935	NAME—Conte nts of the .01 field for the S URROGATE.
	2936	FM_STARTDA TE—Startin g date/tim e for the SURROGATE in interna l VA FileM an format.
	2937	FM_ENDDATE —Ending da te/time fo r the SURR OGATE in i nternal VA FileMan f ormat.
	2938
	2939	Example
	2940	>S X=$$GET SURO^XQALS URO(124)
	2941
	2942	>W X
	2943
	2944	2327^XUUSE R,FOUR^300 0929.1630^ 3001006.08 00
	2945
	2946	This indic ates that user #2327 (Four Xuu ser) becom es active as surroga te at 4:30 PM 9/29/0 0 and rema ins surrog ate until 8:00 am on 10/06/00.
	2947	REMVSURO^X QALSURO(): Remove Su rrogates f or Alerts
	2948	Reference Type:Suppo rted
	2949	Category:A lerts
	2950	ICR #:2790
	2951	Descriptio n:This API removes a ny surroga tes for al erts for t he specifi ed user.
	2952	Format:REM VSURO^XQAL SURO(xqaus er[,.xqals uro][,.xqa lstrt])
	2953	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN, DUZ value) in the NEW PE RSON file (#200) for the speci fied user.
	2954	xqalsuro:( optional) IEN of use r in NEW P ERSON file (#200). I f passed, only the u ser who is passed is removed f rom the li st of surr ogates. If not passe d, only th e current surrogate is removed (if any).
	2955	xqalstrt:( optional) If passed, the surro gate is re moved only from the start date indicated . If not p assed, the surrogate is remove d starting from the date of th e current surrogate (if any). If there i s no curre nt surroga te, no ent ries are r emoved.
	2956	Output:non e.
	2957
	2958	SETSURO1^X QALSURO(): Establish a Surroga te for Ale rts
	2959	Reference Type:Suppo rted
	2960	Category:A lerts
	2961	ICR #:3213
	2962	Descriptio n:This API establish es a surro gate for a lerts. It should be used inste ad of the SETSURO^XQ ALSURO API . The SETS URO1^XQALS URO API al so tests f or cyclic relationsh ips (such that the u ser eventu ally would become th e surrogat e). SETSUR O1 does th ese tests and theref ore has th e possibil ity of fai lure. It r eturns eit her of the following values:
	2963	IEN (value > 0; True )—Surrogat e was crea ted succes sfully.
	2964	Text Strin g (False)— Text expla ining why the surrog ate was no t created.
	2965	Previously , the SETS URO^XQALSU RO API ret urned no v alue and, as long as both a us er and sur rogate wer e specifie d, would s imply stor e the valu es. This l eft open t he possibi lity that the user w as specifi ed as the surrogate or that a chain of s urrogates ended up p ointing ag ain at the user, cas es that co uld result in a very tight, no n-ending, loop being generated if an ale rt was sen t. These p ossibiliti es have be en tested for in the interacti ve specifi cation of surrogates , and is t ested for non-intera ctive usag e in the S ETSURO1^XQ ALSURO API .
	2966	NOTE: The SETSURO1^X QALSURO AP I should b e used ins tead of th e SETSURO^ XQALSURO A PI (i.e., ICR # 2790 ).
	2967	Format:SET SURO1^XQAL SURO(xqaus er,xqalsur o[,xqalstr t][,xqalen d])
	2968	Input Para meters:xqa user:(requ ired) User ’s DUZ num ber (i.e., Internal Entry Numb er in the NEW PERSON file [#20 0]) for wh ich the su rrogate sh ould act i n receivin g alerts.
	2969	xqalsuro:( required) Surrogate’ s DUZ numb er (i.e., Internal E ntry Numbe r in the N EW PERSON file [#200 ]) for the user who receives a nd process es alerts for XQAUSE R.
	2970	xqalstrt:( optional) The start date/time or the sur rogate act ivity, in VA FileMan internal format. If the start date/time is not sp ecified, t he surroga te relatio nship begi ns immedia tely.
	2971	xqalend:(o ptional) T he end dat e/time for the end o f the surr ogate rela tionship, in VA File Man intern al format. If the en d date/tim e is not s pecified, the surrog ate remain s active u ntil anoth er surroga te is spec ified or t he surroga te is dele ted.
	2972	Output:ret urns:Retur ns:
	2973	IEN (value > 0; True )—Surrogat e was crea ted succes sfully.
	2974	Text Strin g (False)— Text expla ining why the surrog ate was no t created.
	2975
	2976	Example
	2977	>S XQAUSER =DUZ
	2978
	2979	>S XQASURR O=45
	2980
	2981	>S XQASTAR T=3001004. 1630
	2982
	2983	>S XQAEND= 3001008.16 30
	2984
	2985	>S X=$$SET SURO1^XQAL SURO(XQAUS ER,XQASURR O,XQASTART ,XQAEND)
	2986
	2987	>I ‘X W !, “Could not activate surrogate” ,!,?5,X Q
	2988
	2989	SUROFOR^XQ ALSURO(): Return a S urrogate’s List of U sers
	2990	Reference Type:Suppo rted
	2991	Category:A lerts
	2992	ICR #:3213
	2993	Descriptio n:This API returns a list of u sers for w hich the u ser, as de fined by t he xqauser input par ameter, is acting as a surroga te.
	2994	Format:SUR OFOR^XQALS URO(xqause r,.xqalist )
	2995	Input Para meters:xqa user:(requ ired) User ’s DUZ num ber (i.e., Internal Entry Numb er in the NEW PERSON file [#20 0]) for wh ich the su rrogate sh ould act i n receivin g alerts.
	2996	xqalist:(r equired) P assed by r eference; it contain s the name of the ou tput array .
	2997	Output:xqa list:The o utput cont ains the l ist of use rs for who m the spec ified user is curren tly acting as a surr ogate. The data in t he list in cludes the :
	2998	User’s int ernal entr y number ( DUZ).
	2999	User’s nam e.
	3000	Start and end dates for the su rrogate pe riod.
	3001	Set to a n umber equa l to the c ount of th e total nu mber of su rrogates r eturned in the list:
	3002	XQALIST(n)
	3003	Where n is a sequent ial intege r starting with 1. E ach entry in the arr ay contain s:
	3004	IEN^Name^S tart Date/ Time^End D ate/Time
	3005
	3006	Example
	3007	>S XQAUSER =DUZ
	3008	>D SUROFOR ^XQALSURO( XQAUSER,.U SERLIST)
	3009	Returns:
	3010	Figure 18: SUROFOR^X QALSURO AP I—Example
	3011	USERLIST=c ount
	3012	USERLIST(1 )=IEN2^NEW PERSON,USE R2^STARTDA TETIME^END DATETIME
	3013	USERLIST(2 )=3^NAME,U SER3^30504 07.1227^30 50406
	3014
	3015	>ZW USERLI ST
	3016	OUTPUT=2
	3017	OUTPUT(1)= “5206652^P ERSON,FIRS T^3071113. 141547^307 1113.142”
	3018	OUTPUT(2)= “5206656^P ERSON,SECO ND^3071114 ^3071114.0 8”
	3019
	3020	SUROLIST^X QALSURO(): List Surr ogates for a User
	3021	Reference Type:Suppo rted
	3022	Category:A lerts
	3023	ICR #:3213
	3024	Descriptio n:This API returns a list of c urrent or future sur rogates fo r the user that is d efined by the xqause r input pa rameter. I t also set s the foll owing surr ogate fiel ds in the ALERT file (#8992) i f there is a current surrogate for this user:
	3025	SURROGATE FOR ALERTS (#.02)
	3026	SURROGATE START DATE /TIME (#.0 3)
	3027	SURROGATE END DATE/T IME (#.04)
	3028	Format:SUR OLIST^XQAL SURO(xqaus er,.xqalis t)
	3029	Input Para meters:xqa user:(requ ired) This is the In ternal Ent ry Number (IEN, DUZ value) in the NEW PE RSON file (#200) for the speci fied user.
	3030	xqalist:(r equired) P assed by r eference; it contain s the name of the ou tput array .
	3031	Output:xqa list:The o utput cont ains the l ist of cur rent and f uture surr ogates for the speci fied user. The data in the lis t includes the follo wing:
	3032	User’s int ernal entr y number ( DUZ).
	3033	User’s nam e.
	3034	Start and end dates for the su rrogate pe riod.
	3035	Set to a n umber equa l to the c ount of th e total nu mber of su rrogates r eturned in the list:
	3036	XQALIST(n)
	3037	Where n is a sequent ial intege r starting with 1. E ach entry in the arr ay contain s:
	3038	IEN^Name^S tart Date/ Time^End D ate/Time
	3039
	3040	Example
	3041	Figure 19: SUROLIST^ XQALSURO A PI—Example
	3042	>D SUROLIS T^XQALSURO (duz,.outp ut)
	3043
	3044	>ZW OUTPUT
	3045	OUTPUT=2
	3046	OUTPUT(1)= “5206652^P ERSON,FIRS T^3071113. 141547^307 1113.142”
	3047	OUTPUT(2)= “5206656^P ERSON,SECO ND^3071114 ^3071114.0 8”
	3048
	3049
	3050
	3051	Common Ser vices: Dev eloper Too ls
	3052	Applicatio n Programm ing Interf ace (API)
	3053	The follow ing are Co mmon Servi ces APIs a vailable f or develop ers. These APIs are described below.
	3054	$$IEN^XUPS (): Get IE N Using VP ID in File #200
	3055	Reference Type:Suppo rted
	3056	Category:C ommon Serv ices
	3057	ICR #:4574
	3058	Descriptio n:This ext rinsic fun ction acce pts the VA Person ID (VPID) of an entry in the NEW PERSON fi le (#200) and return s the Inte rnal Entry Number (I EN)/DUZ. T his API wa s added wi th Kernel patch XU8 .0309.
	3059	CAUTION: V PID has no t been ful ly impleme nted in th e VA. VPID was the u ser identi fier withi n the canc eled Enter prise Sing le Sign-On (ESSO) pr oject. The current I dentity an d Access M anagement (IAM) 2-fa ctor authe ntication project us es Securit y ID (SecI D) as the unique ide ntifier. V PID APIs a nd fields will be de precated i n a future Kernel pa tch. Devel opers are encouraged to remove all refer ences to t hese APIs in their c ode.
	3060	Format:$$I EN^XUPS(vp id)
	3061	Input Para meters:vpi d:(require d) The VA Person ID (VPID).
	3062	Output:ret urns:Retur ns the Int ernal Entr y Number ( IEN)/DUZ o f the NEW PERSON fil e (#200).
	3063
	3064	$$VPID^XUP S(): Get V PID Using IEN in Fil e #200
	3065	Reference Type:Suppo rted
	3066	Category:C ommon Serv ices
	3067	ICR #:4574
	3068	Descriptio n:This ext rinsic fun ction acce pts the in ternal ent ry number (IEN)/DUZ of an entr y in the N EW PERSON file (#200 ) and retu rns the VA Person ID (VPID) fo r the sele cted user. This API was added with Kerne l patch XU 8.0309.
	3069	CAUTION: V PID has no t been ful ly impleme nted in th e VA. VPID was the u ser identi fier withi n the canc eled Enter prise Sing le Sign-On (ESSO) pr oject. The current I dentity an d Access M anagement (IAM) 2-fa ctor authe ntication project us es Securit y ID (SecI D) as the unique ide ntifier. V PID APIs a nd fields will be de precated i n a future Kernel pa tch. Devel opers are encouraged to remove all refer ences to t hese APIs in their c ode.
	3070	Format:$$V PID^XUPS(d uz)
	3071	Input Para meters:duz :(required ) The Inte rnal Entry Number (I EN) in the NEW PERSO N file (#2 00).
	3072	Output:ret urns:Retur ns the VA Person ID (VPID) for the entry found in the NEW PE RSON file (#200).
	3073
	3074	EN1^XUPSQR Y(): Query New Perso n File
	3075	Reference Type:Contr olled Subs cription
	3076	Category:C ommon Serv ices
	3077	ICR #:4575
	3078	Descriptio n:The XUPS PERSONQUE RY RPC use s this API . This API provides the functi onality to query the NEW PERSO N file (#2 00). The c alling app lication c an query t he NEW PER SON file ( #200) by u sing eithe r the Secu rity ID (S ECID) of t he request ed entry o r part/all of a last name. Oth er optiona l paramete rs can be passed to the call a s addition al filters . This API was added with Kern el patch X U8.0325.
	3079	Format:
	3080	EN1^XUPSQR Y(result,x upsecid,xu pslnam[,xu psfnam][,x upsssn][,x upsprov][, xupsstn][, xupsmnm][, xupsdate])
	3081	Input Para meters:res ult:(requi red) Name of the sub scripted r eturn arra y. In ever y API that is used a s an RPC, the first parameter is the ret urn array.
	3082	xupsecid:( required) This param eter conta ins the SE CID for th e requeste d user. Ei ther the S ECID or la st name is required.
	3083	xupslnam:( required) This param eter conta ins all or part of a last name . A last n ame or SEC ID are req uired inpu t variable s.
	3084	xupsfnam:( optional) This param eter is se t to null or the ful l or parti al first n ame.
	3085	xupsssn:(o ptional) T his parame ter is set to null o r contains the 9 dig its of the Social Se curity Num ber (SSN).
	3086	xupsprov:( optional) This param eter is se t to null or “P”. If set to “P ”, it scre ens for pr oviders (p erson with active us er class).
	3087	xupsstn:(o ptional) T his parame ter is set to null o r the Stat ion Number .
	3088	xupsmnm:(o ptional) T his parame ter is set to the ma ximum numb er of entr ies (1-50) to be ret urned. Def aults to 5 0.
	3089	xupsdate:( optional) This param eter conta ins the da te used to determine if person class is active. De faults to current da te.
	3090	Output Par ameters:re sult():Ret urns a sub scripted o utput arra y of the i nput value /subscript ed array ( i.e., list ) with the following possible values sho wn:
	3091	^TMP($J,“X UPSQRY”,1) —1 if foun d, 0 if no t found
	3092	^TMP($J,“X UPSQRY”,n, 0)—VPID^IE N^LastName ~First Nam e~Middle N ame^SSN^DO B^SEX^
	3093	^TMP($J,“X UPSQRY”,n, 1)—Provide r Type^
	3094	^TMP($J,“X UPSQRY”,n, 2)—Provide r Classifi cation^
	3095	^TMP($J,“X UPSQRY”,n, 3)—Provide r Area of Specializa tion^
	3096	^TMP($J,“X UPSQRY”,n, 4)—VA CODE ^X12 CODE^ Specialty Code^end-o f-record c haracter “ \|”\|
	3097
	3098
	3099
	3100	Data Secur ity: Devel oper Tools
	3101	Overview
	3102	Developers can use d ata securi ty tools t o protect informatio n from una uthorized viewing.
	3103	Released w ith Kernel patch XU* 8.0*655, t he Secure Hash Algor ithm is a family of one-way cr yptographi c hash fun ctions. Th e input da ta is ofte n called t he message , and the hash value is often called the message d igest. Cry ptographic hash func tions are used in th e followin g:
	3104	Digital si gnatures.
	3105	Message au thenticati on codes.
	3106	Other form s of authe ntication.
	3107	They can a lso be use d to:
	3108	Detect dup licate dat a.
	3109	Uniquely i dentify fi les.
	3110	Detect acc idental da ta corrupt ion as che cksums.
	3111	In informa tion secur ity contex ts, crypto graphic ha sh values are someti mes called digital f ingerprint s.
	3112	Encryption is the pr ocess of u sing a mat hematical algorithm to transfo rm informa tion so th at it beco mes unread able. The informatio n is then available only to th ose who po ssess the key that c an be used for decry ption.
	3113	Binary-to- text encod ing scheme s are used to repres ent binary data in a n ASCII st ring forma t. They ar e commonly used when there is a need to store or t ransfer da ta over me dia that i s designed to deal w ith textua l data to ensure tha t the data remains i ntact with out modifi cation dur ing transp ort.
	3114	Applicatio n Programm ing Interf ace (API)
	3115	Several AP Is for has hing, enco ding/decod ing, or en cryption/d ecryption of input o f various formats ar e availabl e for deve lopers to work with data secur ity. These APIs are supported under Inte gration Co ntrol Regi stration ( ICR) #6189 and are d escribed b elow.
	3116	$$AESDECR^ XUSHSH(): Returns Pl aintext St ring Value for AES E ncrypted C iphertext Entry
	3117	Reference Type:Suppo rted
	3118	Category:D ata Securi ty
	3119	ICR #:6189
	3120	Descriptio n:This ext rinsic fun ction retu rns the st ring value of an Adv anced Encr yption Sta ndard (AES ) encrypte d cipherte xt entry. AES is a s pecificati on for the encryptio n of elect ronic data establish ed by the U.S. Natio nal Instit ute of Sta ndards and Technolog y (NIST) i n 2001.
	3121	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3122	Format:$$A ESDECR^XUS HSH(text,k ey[,iv])
	3123	Input Para meters:tex t:(require d) The cip hertext st ring to be decrypted .
	3124	key:(requi red) The i nput key m aterial 16 , 24, or 3 2 characte rs long.
	3125	iv:(option al) The in itializati on vector. If this a rgument is present, it must be 16 charac ters long.
	3126	Output:ret urns:Retur ns the pla intext val ue of the AES encryp ted cipher text entry in the te xt input p arameter.
	3127
	3128	Example
	3129	>W $$AESDE CR^XUSHSH( $$B64DECD^ XUSHSH("ST bvalBtOxy7 54eRo15Bkg =="),"Encr 4pt10
	3130	nK3y")
	3131	This is a test
	3132
	3133	$$AESENCR^ XUSHSH(): Returns AE S Encrypte d Cipherte xt for Str ing Entry
	3134	Reference Type:Suppo rted
	3135	Category:D ata Securi ty
	3136	ICR #:6189
	3137	Descriptio n:This ext rinsic fun ction retu rns the Ad vanced Enc ryption St andard (AE S) encrypt ed ciphert ext for a string ent ry. AES is a specifi cation for the encry ption of e lectronic data estab lished by the U.S. N ational In stitute of Standards and Techn ology (NIS T) in 2001 .
	3138	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3139	Format:$$A ESENCR^XUS HSH(text,k ey[,iv])
	3140	Input Para meters:tex t:(require d) The pla intext str ing to be encrypted.
	3141	key:(requi red) The i nput key m aterial 16 , 24, or 3 2 characte rs long.
	3142	iv:(option al) The in itializati on vector. If this a rgument is present, it must be 16 charac ters long.
	3143	Output:ret urns:Retur ns the AES encrypted ciphertex t for the string ent ry in the text input parameter .
	3144
	3145	Example
	3146	NOTE: The AES encryp tion API r eturns Uni code ciphe rtext, whi ch does no t properly display o n an ASCII roll-and- scroll ter minal; so the exampl e demonstr ated outpu t is Base 64 encoded before di splay.
	3147	>W $$B64EN CD^XUSHSH( $$AESENCR^ XUSHSH("Th is is a te st","Encr4 pt10nK3y") )
	3148	STbvalBtOx y754eRo15B kg==
	3149
	3150	$$B64DECD ^XUSHSH(): Returns D ecoded Val ue for a B ase64 Stri ng Entry
	3151	Reference Type:Suppo rted
	3152	Category:D ata Securi ty
	3153	ICR #:6189
	3154	Descriptio n:This ext rinsic fun ction retu rns the de coded valu e for a Ba se64 strin g entry. B ase64 is a binary-to -text enco ding schem e that rep resents bi nary data in an ASCI I string f ormat by t ranslating it into a radix-64 representa tion. Base 64 encodin g is commo nly used w hen there is a need to encode binary dat a that nee ds to be s tored and transferre d over med ia that is designed to deal wi th textual data.
	3155	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3156	Format:$$B 64DECD^XUS HSH(x)
	3157	Input Para meters:x:( required) The string to be dec oded.
	3158	Output:ret urns:Retur ns the dec oded value for the B ase64 inpu t paramete r.
	3159
	3160	Example
	3161	>W $$B64DE CD^XUSHSH( "VGhpcyBpc yBhIHRlc3Q =")
	3162	This is a test
	3163
	3164	$$B64ENCD^ XUSHSH(): Returns Ba se64 Encod ed Value f or a Strin g Entry
	3165	Reference Type:Suppo rted
	3166	Category:D ata Securi ty
	3167	ICR #:6189
	3168	Descriptio n:This ext rinsic fun ction retu rns the Ba se64 encod ed value f or a strin g entry. B ase64 is a binary-to -text enco ding schem e that rep resents bi nary data in an ASCI I string f ormat by t ranslating it into a radix-64 representa tion. Base 64 encodin g is commo nly used w hen there is a need to encode binary dat a that nee ds to be s tored and transferre d over med ia that is designed to deal wi th textual data.
	3169	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3170	Format:$$B 64ENCD^XUS HSH(x)
	3171	Input Para meters:x:( required) The string to be enc oded.
	3172	Output:ret urns:Retur ns the Bas e64 encode d value of the input parameter .
	3173
	3174	Example
	3175	>W $$B64EN CD^XUSHSH( "This is a test")
	3176	VGhpcyBpcy BhIHRlc3Q=
	3177
	3178	$$RSADECR^ XUSHSH(): Returns Pl aintext St ring Value for RSA E ncrypted C iphertext Entry
	3179	Reference Type:Suppo rted
	3180	Category:D ata Securi ty
	3181	ICR #:6189
	3182	Descriptio n:This ext rinsic fun ction retu rns the pl aintext st ring value for an RS A encrypte d cipherte xt entry. RSA is a p ublic-key encryption system th at is wide ly used fo r secure d ata transm ission. Th e encrypti on key is public and differs f rom the de cryption k ey, which is kept se cret.
	3183	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3184	Format:$$R SADECR^XUS HSH(text,k ey[,pwd][, enc])
	3185	Input Para meters:tex t:(require d) The RSA encrypted ciphertex t string t o be decry pted.
	3186	key:(requi red) The R SA private key corre sponding t o the RSA public key that was used for e ncryption, Privacy E nhanced Ma il (PEM) e ncoded.
	3187	pwd:(optio nal) The p rivate key password.
	3188	enc:(optio nal) Encod ing - Publ ic-Key Cry ptography Standards (PKCS) #1 v2.1 encod ing method :
	3189	1—Optimal Asymmetric Encryptio n Padding (OAEP; def ault).
	3190	2—PKCS 1-v 1_5.
	3191	Output:ret urns:Retur ns the pla intext str ing value for the RS A encrypte d cipherte xt input p arameter.
	3192
	3193	Example
	3194	NOTE: "hgw ds" is the alias of a certific ate instal led in Cac hé through the manag ement port al for dem onstration purposes. The priva te key use d to decry pt the cip hertext wa s not avai lable, so that funct ion is not demonstra ted here.
	3195	$$RSAENCR^ XUSHSH(): Returns RS A Encrypte d Cipherte xt for Str ing Entry
	3196	Reference Type:Suppo rted
	3197	Category:D ata Securi ty
	3198	ICR #:6189
	3199	Descriptio n:This ext rinsic fun ction retu rns the RS A encrypte d cipherte xt for a s tring entr y. RSA is a public-k ey encrypt ion system that is w idely used for secur e data tra nsmission. The encry ption key is public and differ s from the decryptio n key, whi ch is kept secret.
	3200	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3201	Format:$$R SAENCR^XUS HSH(text,c ert[,cafil e][,crlfil e][,enc])
	3202	Input Para meters:tex t:(require d) The pla intext str ing to be encrypted.
	3203	cert:(requ ired) An X .509 certi ficate con taining th e RSA publ ic key to be used fo r encrypti on, in PEM encoded o r binary D istinguish ed Encodin g Rules (D ER) format . The leng th of the plaintext cannot be greater th an the len gth of the modulus o f the RSA public key contained in the ce rtificate minus 42 b ytes.
	3204	cafile:(op tional) Th e name of a file con taining th e trusted Certificat e Authorit y X.509 Ce rtificates in PEM-en coded form at, one of which was used to s ign the ce rtificate.
	3205	crlfile:(o ptional) T he name of a file co ntaining X .509 Certi ficate Rev ocation Li sts in PEM -encoded f ormat that should be checked t o verify t he status of the cer tificate.
	3206	enc:(optio nal) Encod ing - PKCS #1 v2.1 e ncoding me thod:
	3207	1—OAEP (de fault).
	3208	2—PKCS 1-v 1_5.
	3209	Output:ret urns:Retur ns the RSA encrypted ciphertex t value of the text input para meter.
	3210
	3211	Example
	3212	NOTE: The RSA encryp tion API r eturns Uni code ciphe rtext, whi ch does no t properly display o n an ASCII roll-and- scroll ter minal; so the exampl e demonstr ated outpu t is Base 64 encoded before di splay.
	3213	>S TEXT="T his is a t est"
	3214
	3215	>S CREDSET =##class(% SYS.X509Cr edentials) .GetByAlia s("hgwds")
	3216
	3217	>S CERT=CR EDSET.Cert ificate
	3218
	3219	>W $$B64EN CD^XUSHSH( $$RSAENCR^ XUSHSH(TEX T,CERT,,,1 ))
	3220	PbFxIUBA+M u5F4rtFHVJ OusYfqFOm9 9eyhp3jYTB BIteSMYE1J +dHFqSePGt GXInBIy2f6 gVxTvf
	3221	WQyy8Le92t bqADftPsGK lBISaA1O3v 2r0oxYQkwR 6FPub3y/r9 2b6l/StwAz ImMF9EP6vq Lt/IOK
	3222	1eu4UD+sT5 qesGB9zgAm EfQgitT3qh XZJZUAbIi/ /NZbLiWVtG F+99GSa77V yMXkWqKiSV ZZHCLG
	3223	yUGgPn8SwF XEsZNs+STu FaQn6jialr n04NOuaqXE DSZu1qGpn5 WE3fNcWeLZ E5sXJX8rG0 uW5R/O
	3224	lx/Xlk3L2G hqELELsgzJ Y0RG5fp8wT 58cJKqwQ==
	3225
	3226	$$SHAHASH^ XUSHSH(): Returns SH A Hash for a String Entry
	3227	Reference Type:Suppo rted
	3228	Category:D ata Securi ty
	3229	ICR #:6189
	3230	Descriptio n:This ext rinsic fun ction retu rns the Se cure Hash Algorithm (SHA) hash for a str ing entry. It uses a n input va riable to specify th e length i n bits of the desire d hash.
	3231	NOTE: This API was r eleased wi th Kernel patch XU8 .0655.
	3232	Format:$$S HAHASH^XUS HSH(n,x[,f lag])
	3233	Input Para meters:n:( required) Length in bits of th e desired hash:
	3234	160 (SHA-1 )
	3235	224 (SHA-2 24)
	3236	256 (SHA-2 56)
	3237	384 (SHA-3 84)
	3238	512 (SHA-5 12)
	3239	x:(require d) String to be hash ed.
	3240	flag:(opti onal) Flag to contro l format o f hash:
	3241	"H"—Hexade cimal (def ault)
	3242	"B"—Base64 Encoded
	3243	Output:ret urns:Retur ns SHA has h for a st ring entry .
	3244
	3245	Examples
	3246	Example 1
	3247	>W $$SHAHA SH^XUSHSH( 256,"This is a test" )
	3248	C7BE1ED902 FB8DD4D489 97C6452F5D 7E509FBCDB E2808B16BC F4EDCE4C07 D14E
	3249	>
	3250
	3251	Example 2
	3252	>W $$SHAHA SH^XUSHSH( 256,"This is a test" ,"B")
	3253	x74e2QL7jd TUiZfGRS9d flCfvNvigI sWvPTtzkwH 0U4=
	3254	>
	3255
	3256
	3257
	3258	Device Han dler: Deve loper Tool s
	3259	Overview
	3260	The Device Handler p rovides a common use r interfac e and deve loper API for using output dev ices. This section d escribes t he Device Handler’s developer API.
	3261	The ZIS* s eries of r outines be comes the Device Han dler when the Kernel installat ion proces s (the ZTM GRSET rout ine) saves them in t he Manager ’s account as %ZIS* routines. A separate set of ZI S* routine s is distr ibuted for each oper ating syst em.
	3262	NOTE: As o f Kernel p atch XU8. 0546 (and Informati onal Patch XU8.055 6), Class 3 routines that are not writte n to permi t queuing no longer output to devices wh ere the QU EUING fiel d (#5.5) i n the DEVI CE file (# 3.5) is se t to FORCE D. Sites t hat have c ompleted t he Linux u pgrade che cklist, sh ould have already ad dressed th is issue.R EF: For mo re specifi c details, see Kerne l Patches XU8.0546 and 556.
	3263	Applicatio n Programm ing Interf ace (API)
	3264	Several AP Is are ava ilable for developer s to work with devic es. These APIs are d escribed b elow.
	3265	DEVICE^XUD HGUI(): GU I Device L ookup
	3266	Reference Type:Suppo rted
	3267	Category:D evice Hand ler
	3268	ICR #:3771
	3269	Descriptio n:This API allows Vi stA Graphi cal User I nterface ( GUI)-based applicati ons to loo k up devic es. This A PI retriev es the fir st 20 devi ces that m eet the sp ecificatio ns passed. This API was made a vailable w ith Kernel patch XU* 8.0*220.
	3270	Format:DEV ICE^XUDHGU I(.list,st arting_poi nt[,direct ion][,righ t_margin_r ange])
	3271	Input Para meters:.li st:(requir ed) Named array to s tore outpu t.
	3272	starting_p oint:(requ ired) This parameter indicates where to start the $ORDERing of the Glo bal. “P” o nly return s devices whose name starts wi th “P”; “P *” returns up to 20 devices th e first st arting wit h “P”.
	3273	direction: (optional) This para meter indi cates whet her to $OR DER up or down from the starti ng_point p arameter. The accept able value s are 1 an d -1:
	3274	1—Up.
	3275	-1—Down.
	3276	right_marg in_range:( optional) This param eter speci fies a wid th range o f devices:
	3277	Exact Widt h (e.g., ” 132-132”)
	3278	At Least W idth (e.g. , ”132”)
	3279	Range (e.g ., ”80-132 ”)
	3280	Output Par ameters:.l ist:The da ta is retu rned in th is named a rray. Data is return ed in the following format:
	3281	IEN^NAME^D ISPLAY NAM E^LOCATION ^RIGHT MAR GIN^PAGE L ENGTH
	3282	Examples
	3283	Example 1
	3284	This examp le stores/ displays a list of a ll devices that begi n with “P” in an arr ay (e.g., DEVICES), without pa ssing a di rection or right mar gin range parameter:
	3285	>K DEVICES
	3286	>D DEVICE^ XUDHGUI(.D EVICES,“P” )
	3287
	3288	The DEVICE S array di splays the following results:
	3289	Figure 20: DEVICE^XU DHGUI API— Example 1: DEVICES a rray displ aying samp le results
	3290	>ZW DEVICE S
	3291	DEVICES(1) =358^P-MES SAGE-HFS^P -MESSAGE-H FS^HFS FIL E=>MESSAGE ^255^256
	3292	DEVICES(2) =348^P-MES SAGE-HFS-O NT^P-MESSA GE-HFS-ONT ^HFS FILE= => MESSAGE ^80^999
	3293	DEVICES(3) =274^P-MES SAGE-HFS-V XD^P-MESSA GE-HFS-VXD ^HFS FILE= => MESSAGE ^80^256
	3294	DEVICES(4) =292^P-RES MON^P-RESM ON^IRM^132 ^64
	3295	DEVICES(5) =310^P-WIN DOC^P-WIND OC^MWI WIN DOW DOCUME NT BOX^80^ 256
	3296
	3297	Example 2
	3298	This examp le stores/ displays a list of a ll devices that begi n with “P” in an arr ay (e.g., DEVICES), without pa ssing a di rection pa rameter bu t includin g those de vices with a right m argin of a n exact wi dth of 80:
	3299	>K DEVICES
	3300	>D DEVICE^ XUDHGUI(.D EVICES,“P” ,,“80-80”)
	3301
	3302	The DEVICE S array di splays the following results:
	3303	Figure 21: DEVICE^XU DHGUI API— Example 2: DEVICES a rray displ aying samp le results
	3304	>ZW DEVICE S
	3305	DEVICES(1) =348^P-MES SAGE-HFS-O NT^P-MESSA GE-HFS-ONT ^HFS FILE= => MESSAGE ^80^999
	3306	DEVICES(2) =274^P-MES SAGE-HFS-V XD^P-MESSA GE-HFS-VXD ^HFS FILE= => MESSAGE ^80^256
	3307	DEVICES(3) =310^P-WIN DOC^P-WIND OC^MWI WIN DOW DOCUME NT BOX^80^ 256
	3308
	3309	Example 3
	3310	This examp le stores/ displays a list of a ll devices that begi n with “P” in an arr ay (e.g., DEVICES), without pa ssing a di rection pa rameter bu t includin g those de vices with a right m argin widt h range of 80-132:
	3311	>K DEVICES
	3312	>D DEVICE^ XUDHGUI(.D EVICES,“P” ,,“80-132” )
	3313
	3314	The DEVICE S array di splays the following results:
	3315	Figure 22: DEVICE^XU DHGUI API— Example 3: DEVICES a rray displ aying samp le results
	3316	>ZW DEVICE S
	3317	DEVICES(1) =348^P-MES SAGE-HFS-O NT^P-MESSA GE-HFS-ONT ^HFS FILE= => MESSAGE ^80^999
	3318	DEVICES(2) =274^P-MES SAGE-HFS-V XD^P-MESSA GE-HFS-VXD ^HFS FILE= => MESSAGE ^80^256
	3319	DEVICES(3) =292^P-RES MON^P-RESM ON^IRM^132 ^64
	3320	DEVICES(4) =310^P-WIN DOC^P-WIND OC^MWI WIN DOW DOCUME NT BOX^80^ 256
	3321
	3322	Example 4
	3323	This examp le stores/ displays a list of u p to 20 de vices, the first of which star ts with “P ,” in an a rray (e.g. , DEVICES) , without passing a direction or right m argin rang e paramete r:
	3324	>K DEVICES
	3325	>D DEVICE^ XUDHGUI(.D EVICES,“P* ”)
	3326
	3327	The DEVICE S array di splays the following results:
	3328	Figure 23: DEVICE^XU DHGUI API— Example 4: DEVICES a rray displ aying samp le results
	3329	>ZW DEVICE S
	3330	DEVICES(1) =358^P-MES SAGE-HFS^P -MESSAGE-H FS^HFS FIL E=>MESSAGE ^255^256
	3331	DEVICES(2) =348^P-MES SAGE-HFS-O NT^P-MESSA GE-HFS-ONT ^HFS FILE= => MESSAGE ^80^999
	3332	DEVICES(3) =274^P-MES SAGE-HFS-V XD^P-MESSA GE-HFS-VXD ^HFS FILE= => MESSAGE ^80^256
	3333	DEVICES(4) =292^P-RES MON^P-RESM ON^IRM^132 ^64
	3334	DEVICES(5) =310^P-WIN DOC^P-WIND OC^MWI WIN DOW DOCUME NT BOX^80^ 256
	3335	DEVICES(6) =202^C6_SD D_MX3 ROUT INE^ROUTIN E <C6_SDD_ MX3 ROUTIN E>^Next to Jean’s Of fice^80^59
	3336	DEVICES(7) =428^SDD D UPLEX P10^ SDD DUPLEX P10^SSD D UPLEX PRIN TER NEXT T O JACK^80^ 60
	3337	DEVICES(8) =429^SDD P 10^SDD P10 ^Printer n ext to Jac k.^80^60
	3338	DEVICES(9) =329^C6_SD D_MX3 P10^ SS10 <C6_S DD_MX3 P10 >^Near Jea n’s Office ^80^59
	3339	DEVICES(10 )=330^C6_S DD_MX3 P12 ^SS12 <C6_ SDD_MX3 P1 2>^Near Je an’s Offic e^96^57
	3340	DEVICES(11 )=331^C6_S DD_MX3 P16 ^SS16 <C6_ SDD_MX3 P1 6>^Near Je an’s Offic e^255^58
	3341	DEVICES(12 )=349^C6_S DD_MX3 P16 P8L^SS16P8 L <C6_SDD_ MX3 P16P8L >^Near Jea n’s Office ^117^79
	3342	DEVICES(13 )=202^C6_S DD_MX3 ROU TINE^SSR < C6_SDD_MX3 ROUTINE>^ Next to Je an’s Offic e^80^59
	3343	DEVICES(14 )=427^SUP$ PRT TEST^S UP$PRT TES T^DISK FIL E^132^58
	3344	DEVICES(15 )=283^SYS$ INPUT^SYS$ INPUT^SYS$ INPUT;^132 ^64
	3345	DEVICES(16 )=198^VMS FILE^VMS F ILE^DISK^8 0^64
	3346	DEVICES(17 )=349^C6_S DD_MX3 P16 P8L^VPM <C 6_SDD_MX3 P16P8L>^Ne ar Jean’s Office^117 ^79
	3347	DEVICES(18 )=291^VTB2 55^VTB255^ RMS FILE^2 55^99999
	3348	DEVICES(19 )=288^ZBRO WSE^ZBROWS E^RMS FILE ^255^99999
	3349
	3350	$$RES^XUDH SET(): Set Up Resour ce Device
	3351	Reference Type:Suppo rted
	3352	Category:D evice Hand ler
	3353	ICR #:2232
	3354	Descriptio n:This ext rinsic fun ction sets up a Reso urce devic e. It retu rns:
	3355	Error: -1^ text
	3356	Successful : IEN^devi ce name
	3357	Format:$$R ES^XUDHSET (device_na me[,resour ce_name],s lot_count, descriptio n,subtype)
	3358	Input Para meters:dev ice_name:( required) The name o f the reso urce devic e.
	3359	resource_n ame:(optio nal) The r esource na me if not the same a s the devi ce name.
	3360	slot_count :(required ) The numb er of conc urrent job s that can use this device. It defaults to 1.
	3361	descriptio n:(require d) The dev ice descri ption. It defaults t o “Resourc e Device”.
	3362	subtype:(r equired) T he subtype to use. I t defaults to P-OTHE R.
	3363	Output:ret urns:Retur ns:
	3364	Error: -1^ text
	3365	Successful : IEN^devi ce name
	3366
	3367	^%ZIS: Sta ndard Devi ce Call
	3368	Reference Type:Suppo rted
	3369	Category:D evice Hand ler
	3370	ICR #:1008 6
	3371	Descriptio n:This API allows yo u to selec t a device .
	3372	All input variables are option al. Non-na mespaced v ariables t hat are de fined and later KILL ed by ^%ZI S include: %A, %E, % H, %X, and %Y.
	3373	If device selection is success ful, chara cteristics of the ou tput devic e are retu rned in a number of different variables. If select ion is uns uccessful, ^%ZIS ret urns the P OP output variable w ith a posi tive numbe r. So, che cks for an unsuccess ful device selection should be based on the POP in put variab le as a po sitive num ber.
	3374	Device sel ection can be done a s shown in the examp le that fo llows.
	3375	REF: For a discussio n of form feeds, see the “Form Feeds” se ction in t he “Specia l Device I ssues” sec tion.
	3376	Format:^%Z IS
	3377	Make sure to perform the follo wing steps before ca lling this API:
	3378	NEW all no n-namespac ed variabl es.
	3379	Set all in put variab les.
	3380	Call the A PI.
	3381	Input Vari able:%ZIS: (optional) The %ZIS input vari able is de fined as a string co ntaining o ne or more single-ch aracter fl ags that a ct as inpu t specific ations. Th e function s of each of the fla gs that ca n be inclu ded in the string ar e describe d below. I f the %ZIS input var iable cont ains:
	3382	M—RIGHT MA RGIN: The user is pr ompted wit h the righ t margin q uery.
	3383	N—NO OPENI NG: The De vice Handl er returns the chara cteristics of the se lected dev ice withou t issuing the OPEN c ommand to open the d evice.
	3384	P (obsolet e)—CLOSEST PRINTER: The closes t printer, if one ha s been def ined in th e DEVICE f ile (#3.5) , is prese nted at th e default response t o the devi ce prompt.
	3385	Q—QUEUING ALLOWED: T he job can be queued to run la ter. There is no aut omatic lin k between the Device Handler a nd TaskMan . If queui ng is allo wed, just before the Device Ha ndler is c alled, the applicati on routine must set the %ZIS i nput varia ble to a s tring that includes the letter “Q”. For example:
	3386	>S %ZIS=“M Q” D ^%ZIS
	3387	If the use r selects queuing, t he Device Handler de fines the IO(“Q”) in put variab le as an o utput vari able, to i ndicate th at queuing was selec ted. If qu euing is s elected, t he applica tion shoul d set the needed Tas kMan varia bles and c all the Ta skMan inte rface rout ine ^%ZTLO AD.
	3388	REF: For f urther det ails on ho w to call the TaskMa n interfac e, see the “TaskMan: Developer Tools” se ction.
	3389	0—DON’T US E IO(0): T he Device Handler do es not att empt to us e IO(0), t he home de vice at th e time of the call t o ^%ZIS.
	3390	D—DIRECT P RINTING: I f the sele cted devic e is unava ilable, it returns a positive number in POP.
	3391	L—RESET IO (“ZIO”): I f %ZIS con tains L, t he IO(“ZIO ”) output variable i s reset wi th the sta tic physic al port na me (e.g., the port n ame from a Terminal Server). I t is usefu l when the $I of the M impleme ntation do es not rep resent a p hysical po rt name.
	3392	%ZIS(“A”): (optional) Use to re place the default de vice promp t.
	3393	%ZIS(“B”): (optional) If %ZIS i s defined, HOME is p resented a s the defa ult respon se to the device pro mpt. Use % ZIS(“B”) t o replace this defau lt with an other resp onse.
	3394	>S %ZIS(“B ”)=“”
	3395	(If you do not want to display any defau lt respons e.)
	3396	%ZIS(“HFSM ODE”):(opt ional) Use to pass t he Host fi le access mode to %Z IS. The po ssible val ues are:
	3397	“RW” (whic h may not work in al l environm ents)—READ /WRITE acc ess.
	3398	“R”—READ O nly access .
	3399	“W”—WRITE access.
	3400	“A”—Append mode.
	3401	For exampl e:
	3402	>S %ZIS(“H FSMODE”)=“ R”
	3403	%ZIS(“HFSN AME”):(opt ional) Use to pass t he name of a Host fi le to %ZIS . For exam ple:
	3404	>S %ZIS(“H FSNAME”)=“ MYFILE.DAT ”
	3405	%ZIS(“IOPA R”):(optio nal) Use t his input variable t o pass ope n command variables to the Dev ice Handle r. If defi ned, the v alue of th is input v ariable is used inst ead of any value spe cified in the OPEN P ARAMETERS field of t he DEVICE file (#3.5 ). The Dev ice Handle r uses the data from either th is input v ariable or from the OPEN PARAM ETERS fiel d whether or not the device ty pe is TRM.
	3406	On some M systems, R ight Margi n is an OP EN PARAMET ERS. There fore, any value for Right Marg in in the DEVICE fil e (#3.5), TERMINAL T YPE file ( #3.2), or user respo nse can be ignored w hen this i nput varia ble is use d.
	3407	To set OPE N PARAMETE RS for the tape driv e device, a device w ith $I=47 and device name of M AGTAPE, th e followin g code cou ld be used :
	3408	>S %ZIS(“I OPAR”)=“(” “VAL4”“:0: 2048)”
	3409	>S IOP=“MA GTAPE” D ^ %ZIS
	3410	NOTE: The specific v ariables y ou pass ma y not be f unctional for all op erating sy stems. Use of this f eature sho uld be lim ited to lo cal develo pment effo rts.
	3411	%ZIS(“IOUP AR”):(opti onal) Use this input variable in the sam e way as % ZIS(“IOPAR ”), but fo r variable s to the U SE (rather than OPEN ) command. Any USE P ARAMETERS specified in the DEV ICE file ( #3.5) is o verridden. For examp le:
	3412	>S %ZIS(“I OUPAR”)=“N OECHO”
	3413	>S IOP=“C7 2” D ^%ZIS
	3414	%ZIS(“S”): (optional) Use this input vari able to sp ecify a de vice selec tion scree n. The str ing of M c ode this i nput varia ble is set to should contain a n IF state ment to se t the valu e of $T. T hose entri es that th e IF sets as $T=0 ar e not disp layed or s electable. Like comp arable VA FileMan sc reens, %ZI S(“S”) sho uld be set to sort o n nodes an d pieces, without us ing input variables like ION o r IOT. As with VA Fi leMan, the variable “Y” can be used in t he screen to refer t o the Inte rnal Entry Number (I EN) of the device. A lso, the M naked ind icator is at the glo bal level ^%ZIS(1,Y, 0).
	3415	An example to limit device sel ection to spool devi ce types ( SPL) only might be c oded as fo llows:
	3416	>S %ZIS(“S ”)=“I $G(^ (”“TYPE”“) )=”“SPL”“”
	3417	IOP:(optio nal) Use I OP to spec ify the ou tput devic e. There i s no user interactio n when IOP is define d to speci fy an outp ut device; the devic e name (.0 1 field) i s the usua l value of IOP. You can also s et IOP to Q and P. ( The value of IOP mus t not be $ I).
	3418	NOTE: If I OP is set to NULL, t he device handler de faults to the HOME d evice.
	3419	You can re quest queu ing by set ting IOP=“ Q”. The us er is then asked to specify a device for queuing. To pre-sel ect the de vice, set IOP=“Q;dev ice”; the device spe cified aft er the sem icolon is selected a nd IO(“Q”) is set.
	3420	You can re quest the closest pr inter, as specified in the DEV ICE file ( #3.5), by setting IO P=“P” or I OP=“p”. If there is not a clos est printe r associat ed with th e home dev ice at the time of t he call, d evice sele ction fail s and POP is returne d with a p ositive va lue.
	3421	You can al so pass th e Internal Entry Num ber (IEN) of the des ired devic e through IOP. For i nstance, t o select a device wi th an IEN of 202, yo u can set IOP to an accent gra ve charact er (`) fol lowed by t he IEN val ue of 202 before the call to ^ %ZIS. The following example il lustrates the above call:
	3422	>S IOP=“`2 02” D ^%ZI S
	3423	Using the IEN rather than devi ce name ca n be usefu l when app lications have the d esired dev ice stored as a poin ter to the DEVICE fi le (#3.5) rather tha n as FREE TEXT.
	3424	Output Var iables:IO: If a devic e is succe ssfully op ened, IO i s returned with the device $I value of t he selecte d device. If an abno rmal exit occurs, PO P is retur ned with a positive numeric va lue and IO is return ed as NULL .
	3425	CAUTION: B ecause the returned value of I O can be c hanged, si nce Decemb er 1990, d evelopers have been advised to check for a positiv e value in POP rathe r for IO e qual to NU LL when de termining if an abno rmal exit occurred.
	3426	IO(0):HOME DEVICE—Co ntains the $I value of the hom e device a t the time of the ca ll to the Device Han dler. Sinc e it is de fined at t he time of the call, there is obviously no restora tion after the call.
	3427	IO(1,$I):O PENED DEVI CES—This a rray conta ins a list of device s opened f or the cur rent job b y the Devi ce Handler . The firs t subscrip t of this array is “ 1”. The se cond subsc ript is th e $I value of the de vice opene d. The dat a value is NULL. The Device Ha ndler sets , KILLs, a nd checks the existe nce of IO( 1,IO).
	3428	NOTE: This array sho uld not be altered b y applicat ions outsi de of Kern el.
	3429	IO(“CLNM”) :This vari able holds the name of the rem ote system . It is de fined via the RPC Br oker.
	3430	IO(“CLOSE” ):Device c losed.
	3431	IO(“DOC”): SPOOL DOCU MENT NAME— If output has been s ent to the spool dev ice, this output var iable hold s the name of the sp ool docume nt that wa s selected .
	3432	NOTE: This variable is KILLed when a cal l is made to ^%ZIS o r HOME^%ZI S: Reset H ome Device IO Variab les APIs.
	3433	IO(“HFSIO” ):HOST FIL E DEVICE I O—This is defined by the Devic e Handler when a use r queues t o a file a t the host operating system le vel (of a layered sy stem) and selects a file name other than the defau lt. This H ost file s ystem devi ce input v ariable sh ould have the same v alue as th at stored in the IO output var iable. If IO(“HFSIO” ) exists w hen the Ta skMan inte rface is c alled, the interface saves IO( “HFSIO”) a nd IOPAR s o that the scheduled task open s the appr opriate Ho st file.
	3434	NOTE: This variable is KILLed when a cal l is made to ^%ZIS o r HOME^%ZI S: Reset H ome Device IO Variab les APIs.
	3435	IO(“IP”):T his variab le holds t he Interne t Protocol (IP) of t he remote system.
	3436	IO(“P”):Th is variabl e holds da ta about t he new syn tax reques ted.
	3437	IO(“Q”):OU TPUT WAS Q UEUED—If q ueuing is allowed (% ZIS[“Q”) a nd an outp ut device for queuin g is selec ted, this output var iable is r eturned wi th a value of 1: IO( “Q”)=1. Ot herwise, i t is undef ined.
	3438	NOTE: This variable is KILLed when a cal l is made to ^%ZIS o r HOME^%ZI S: Reset H ome Device IO Variab les APIs.
	3439	IO(“S”):SL AVED DEVIC E—When a s laved prin ter is sel ected, the Device Ha ndler uses this outp ut variabl e to save the subtyp e specific ation for the home d evice so t hat the ap propriate close prin ter logic can be exe cuted with X ^%ZIS(“ C”).
	3440	IO(“SPOOL” ):SPOOLER WAS USED—T he existen ce of this output va riable ind icates tha t output w as sent to the spool device. I t exists t emporarily , during s pooling, a nd is KILL ed upon no rmal exit.
	3441	NOTE: This variable is KILLed when a cal l is made to ^%ZIS o r HOME^%ZI S: Reset H ome Device IO Variab les APIs.
	3442	IO(“T”):Ta skMan call .
	3443	IO(“ZIO”): TERMINAL S ERVER PORT —If %ZIS[“ L”, both p hysical po rt and ser ver names are return ed in IO(“ ZIO”) unde r Caché. T his inform ation is u seful on M implement ations whe re the val ue of $I d oes not re present a port on a Terminal S erver.
	3444	IOBS:BACKS PACE—The c ode for ba ckspace, u sually $C( 8), is ret urned in t his output variable. This code WRITEs a backspace with W @IO BS.
	3445	IOCPU:CPU INDICATOR— If the sel ected devi ce is on a nother CPU , this out put variab le is retu rned with the other CPU refere nce, obtai ned from t he VOLUME SET (CPU) field in t he DEVICE file (#3.5 ). TaskMan uses the IOCPU inpu t variable as an ind icator of where the job should ultimatel y be run.
	3446	IOF:FORM F EED—This o utput vari able issue s a form f eed when w riting its value wit h indirect ion; that is, W @IOF .
	3447	IOM:RIGHT MARGIN—The right mar gin is com monly set to either 80 or 132 columns.
	3448	ION:DEVICE NAME—This variable returns th e device N AME (.01 f ield) as r ecorded in the DEVIC E file (#3 .5).
	3449	IOPAR:OPEN PARAMETER S—This var iable retu rns any OP EN PARAMET ERS that m ay have be en defined for the s elected de vice, for example, a magnetic tape drive . If the O PEN PARAME TERS input variable has not be en defined , IOPAR is returned as NULL.
	3450	NOTE: When a device is closed, this vari able gets set to NUL L.
	3451	IOUPAR:USE PARAMETER S—This var iable retu rns any US E PARAMETE RS that ma y have bee n defined for the se lected dev ice. If th e USE PARA METERS inp ut variabl e has not been defin ed, IOUPAR is return ed as NULL .
	3452	NOTE: When a device is closed, this vari able gets set to NUL L.
	3453	IOS:DEVICE NUMBER—Th e DEVICE f ile (#3.5) Internal Entry Numb er (IEN) f or the sel ected devi ce.
	3454	IOSL:SCREE N/PAGE LEN GTH—The nu mber of li nes per sc reen or pa ge is defi ned with t his variab le. The pa ge length of a print ing device is usuall y 66 lines . The scre en length of a displ ay termina l is usual ly 24 line s.
	3455	IOST:SUBTY PE NAME—Th is variabl e returns the NAME ( .01 field) of the se lected dev ice’s subt ype as rec orded in t he TERMINA L TYPE fil e (#3.2).
	3456	IOST(0):SU BTYPE NUMB ER—This va riable ret urns the I nternal En try Number (IEN) of the select ed device’ s subtype as recorde d in the T ERMINAL TY PE file (# 3.2).
	3457	IOT:TYPE O F DEVICE—T he DEVICE file (#3.5 ) holds an indicatio n of Type for all de vices. IOT returns t he value o f the devi ce type (e .g., TRM f or termina l, VTRM fo r virtual terminal, and HFS fo r Host Fil e Server).
	3458	IOXY:CURSO R POSITION ING—This o utput vari able retur ns the exe cutable M code that allows cur sor positi oning, giv en the inp ut variabl es DX and DY. The co lumn posit ion is pas sed in DX and the ro w position is passed in DY.
	3459	NOTE: The system spe cial varia bles $X an d $Y are n ot necessa rily updat ed.
	3460	POP:EXIT S TATUS—When the Devic e Handler is called, POP is th e output v ariable th at indicat es the out come statu s. If devi ce selecti on is succ essful, PO P is retur ned with a value of zero (POP= 0). Abnorm al exit re turns a po sitive num ber in the POP varia ble.
	3461	There are three gene ral condit ions for a bnormal ex it upon wh ich the PO P output v ariable is returned as positiv e:
	3462	The first case is on e in which a device is not sel ected.
	3463	The second concerns unavailabl e devices.
	3464	The third situation arises whe n a device is identi fied but i s unknown to the sys tem.
	3465	The first condition of no devi ce selecti on is met if the use r types a caret (“^” ) or times out at th e device p rompt. Exc eeding the TIMED REA D at the r ight margi n or addre ss/variabl es prompts has the s ame result .
	3466	The second condition , unavaila bility, is met if th e Device H andler can not open t he selecte d device. The select ed device may also h ave existe d on anoth er compute r but queu ing was no t requeste d or perha ps not per mitted (%Z IS had not contained Q).
	3467	Finally, t he selecte d device m ay not exi st in the DEVICE fil e (#3.5). A device n ame may ha ve been us ed that is not found as a .01 field entr y. If the device is selected w ith P for the closes t printer, the CLOSE ST PRINTER field in the DEVICE file (#3. 5) may be NULL.
	3468	If the exi t is abnor mal, retur ning POP w ith a posi tive value , the foll owing outp ut variabl es are res tored with their val ues before the call to the Dev ice Handle r (before D ^%ZIS): ION, IOF, IOSL, IOBS , IOST(0), IOST, IOP AR, IOUPAR , IOS, and IOCPU.
	3469	NOTE: If I OF had bee n NULL bef ore the ca ll, it is returned w ith the po und sign a s its valu e (IOF=“#” ). For bac kward comp atibility, IO is cur rently ret urned as N ULL (IO=“” ). However , the retu rned value of IO may change in future Ke rnel versi ons.
	3470	Examples
	3471	Example 1
	3472	This follo wing is a simplified example; the proces s of issui ng form fe eds is not shown.
	3473	Figure 24: ^%ZIS API —Example
	3474	SAMPLE ; SAMPLE ROU TINE
	3475	;
	3476	S %ZIS= “QM” D ^%Z IS G EXIT: POP
	3477	I $D(IO (“Q”)) D Q
	3478	.S ZTRT N=“DQ^SAMP LE”,ZTDESC =“Sample T est routin e”
	3479	.D ^%ZT LOAD D HOM E^%ZIS K I O(“Q”) Q
	3480	DQ U IO W !,“THIS IS YOUR REPO RT”
	3481	W !,“LI NE 2”
	3482	W !,“LI NE 3”
	3483	D ^%ZIS C
	3484	EXIT S :$D(ZTQUEU ED) ZTREQ= “@” K VAR1 ,VAR2,VAR3 Q
	3485
	3486	Example 2
	3487	The IOP va riable can be define d to pass a string t o the Devi ce Handler so that n o user int eraction i s required for devic e selectio n informat ion. The f ollowing i s the gene ral format for defin ing IOP:
	3488	>S IOP=[Q[ ;]][DEVICE NAME][;SU BTYPE][;SP OOL DOCUME NT NAME][; RIGHT MARG IN[;PAGE L ENGTH]]
	3489
	3490	Example 3
	3491	If the SPO OL DOCUMEN T NAME is included, then the R IGHT MARGI N and PAGE LENGTH ar e ignored. Therefore , use the following format if a spool de vice is de sired:
	3492	>S IOP=[Q[ ;]][DEVICE NAME][;SU BTYPE][;SP OOL DOCUME NT NAME]
	3493
	3494	Example 4
	3495	The follow ing shows how a devi ce named “ RXPRINTER” in the DE VICE file (#3.5) can be opened without u ser intera ction:
	3496	>S IOP=“RX PRINTER” D ^%ZIS Q:P OP
	3497
	3498	Example 5
	3499	When setti ng the IOP variable, you can i nclude the right mar gin:
	3500	>S IOP=ION _”;”_IOM or S IOP= “;120”
	3501
	3502	Or:
	3503	>S IOP=“RX PRINTER;12 0”
	3504
	3505	In this ex ample, ION is the lo cal variab le that co ntains the name of t he device to be open ed and the IOM varia ble contai ns the val ue of the desired ri ght margin .
	3506	Example 6
	3507	The IOP va riable can be set to FORCED qu euing by s tarting th e string w ith “Q”:
	3508	>SET IOP=“ Q;”_ION_”; ”_IOM ... etc.
	3509
	3510	In order t o force qu euing and prompt the user for a device:
	3511	>SET IOP=“ Q” D ^%ZIS Q:POP
	3512
	3513	Example 7
	3514	A spool do cument nam e can be p assed to t he Device Handler:
	3515	>S IOP=DEV NAM_”;”_IO (“DOC”) D ^%ZIS Q:PO P
	3516
	3517	Or:
	3518	>S IOP=“SP OOL;”_IO(“ DOC”)
	3519
	3520	Or:
	3521	>S IOP=DEV NAM_”;”_IO ST_”;”_IO( “DOC”)
	3522
	3523	Or:
	3524	>S IOP=“SP OOL;P-OTHE R;MYDOC”
	3525	REF: For m ore inform ation, see the “Spoo ling” sect ion in the Kernel Sy stems Mana gement Gui de.
	3526	In this ex ample, DEV NAM contai ns the nam e of the d evice to b e opened. IO(“DOC”) contains t he spool d ocument na me, and IO ST contain s the name of the de sired subt ype. “SPOO L” is the actual nam e of a dev ice entry that corre sponds to the spool device, “P -OTHER” is the desir ed subtype , and “MYD OC” is the name of t he spool d ocument.
	3527	Example 8
	3528	Finally, t he IOP var iable can be used to select a device by the device ’s Interna l Entry Nu mber (IEN) . To selec t a device with an I EN of 202, set IOP t o an accen t grave ch aracter fo llowed by the IEN va lue of 202 :
	3529	>S IOP=“`2 02” D ^%ZI S
	3530
	3531	Multiple D evices and ^%ZIS
	3532	Beyond the home devi ce, the ^% ZIS API is not desig ned to ope n more tha n one addi tional dev ice at a t ime.
	3533	For intera ctive user s, the hom e device s hould alre ady be ope n and defi ned in the Kernel en vironment. ^%ZIS sho uld only b e used to open one a dditional device at a time for interacti ve users. For a task , you can use ^%ZIS to open on e addition al device beyond the task’s as signed dev ice.
	3534	Beginning with Kerne l 8.0, the re are thr ee APIs to support u sing more than one a dditional device sim ultaneousl y:
	3535	OPEN^%ZISU TL(): Open Device wi th Handle
	3536	USE^%ZISUT L(): Use D evice Give n a Handle
	3537	CLOSE^%ZIS UTL(): Clo se Device with Handl e
	3538	These “mul tiple devi ce” APIs a re describ ed later i n this sec tion.
	3539	Host Files and ^%ZIS
	3540	Although i t is possi ble to use the ^%ZIS API to ma nipulate H ost files, the Host file API ( in ^%ZISH) offers mo re robust Host file functional ity.
	3541	REF: For m ore inform ation on u sing the H ost file A PI, see th e “Host Fi les” secti on.
	3542	HLP1^%ZIS: Display B rief Devic e Help
	3543	Reference Type:Suppo rted
	3544	Category:D evice Hand ler
	3545	ICR #:1008 6
	3546	Descriptio n:This API displays brief help about dev ice select ion. There are no in put parame ters.
	3547	While invo king the H elp Proces sor involv es a strai ghtforward call in t he product ion accoun t (the EN^ XQH or EN1 ^XQH calls ), it is a more comp lex matter in the Ma nager acco unt where ^%ZIS resi des. Hence , this cal l is provi ded.
	3548	Format:HLP 1^%ZIS
	3549	Input Para meters:non e.
	3550	Output:non e.
	3551
	3552	HLP2^%ZIS: Display D evice Help Frames
	3553	Reference Type:Suppo rted
	3554	Category:D evice Hand ler
	3555	ICR #:1008 6
	3556	Descriptio n:This API allows yo u to displ ay extende d help abo ut device selection. The Help Processor is invoked to displa y a series of help f rames. The re are no input para meters.
	3557	While invo king the H elp Proces sor involv es a strai ghtforward call in t he product ion accoun t (the ACT ION^XQH4() : Print He lp Frame T ree or EN1 ^XQH: Disp lay Help F rames APIs ), it is a more comp lex matter in the Ma nager acco unt where ^%ZIS resi des. Hence , this cal l is provi ded.
	3558	Format:HLP 2^%ZIS
	3559	Input Para meters:non e.
	3560	Output:non e.
	3561
	3562	HOME^%ZIS: Reset Hom e Device I O Variable s
	3563	Reference Type:Suppo rted
	3564	Category:D evice Hand ler
	3565	ICR #:1008 6
	3566	Descriptio n:This API sets the key IO var iables to match the characteri stics of t he home de vice. The HOME^%ZIS API perfor ms the sam e function as the ob solete CUR RENT^%ZIS API. Devel opers have been advi sed that K ernel 8.0 is the las t version of Kernel to support CURRENT^% ZIS.
	3567	HOME^%ZIS, beyond up dating the set of va riables fo r the home device, a lso update s the acti ve right m argin syst em setting for the h ome device , by execu ting ^%ZOS F(“RM”) ba sed on the home devi ce’s IOM v alue.
	3568	Format:HOM E^%ZIS
	3569	Make sure to perform the follo wing steps before ca lling this API:
	3570	NEW all no n-namespac ed variabl es.
	3571	Set all in put variab les.
	3572	Call the A PI.
	3573	Input Vari ables:none .
	3574	Output Var iables:IO: Device $I.
	3575	IO(0):Home device at the time of the cal l to ^%ZIS .
	3576	IOBS:Backs pace code.
	3577	IOF:Form F eed code.
	3578	IOM:Right Margin len gth.
	3579	ION:Name o f last sel ected inpu t/output d evice from the DEVIC E file (#3 .5).
	3580	IOS:Intern al Entry N umber (IEN ) of last selected i nput/outpu t device f rom the DE VICE file (#3.5).
	3581	IOSL:Scree n or page length.
	3582	IOST:Subty pe of the selected d evice.
	3583	IOST(0):Su btype Inte rnal Entry Number (I EN).
	3584	IOT:Type o f device, such as TR M for term inal.
	3585	IOXY:Execu table M co de for cur sor contro l.
	3586
	3587	$$REWIND^% ZIS(): Rew ind Device s
	3588	Reference Type:Suppo rted
	3589	Category:D evice Hand ler
	3590	ICR #:1008 6
	3591	Descriptio n:This ext rinsic fun ction rewi nds specia l devices. These dev ices may b e of the f ollowing t ypes:
	3592	Magtape
	3593	Sequential Disk Proc essor
	3594	Host File Server
	3595	Format:$$R EWIND^%ZIS (io,iot,io par)
	3596	Input Para meters:io: (required) The $IO r epresentat ion of the device to be rewoun d, in the same forma t as IO, w hich is re turned by ^%ZIS.
	3597	iot:(requi red) The “ Type” of d evice to b e rewound, in the sa me format as IOT, wh ich is ret urned by ^ %ZIS.
	3598	iopar:(req uired) The “Open Par ameters” f or the sel ected devi ce, in the same form at as IOPA R which is returned by ^%ZIS.
	3599	Output:ret urns:Retur ns:
	3600	1—Device w as rewound successfu lly.
	3601	0—Device w as not rew ound succe ssfully.
	3602
	3603	Example
	3604	>S Y=$$REW IND^%ZIS(I O,IOT,IOPA R)
	3605
	3606	^%ZISC: Cl ose Device
	3607	Reference Type:Suppo rted
	3608	Category:D evice Hand ler
	3609	ICR #:1008 9
	3610	Descriptio n:This API closes a device ope ned with a call to t he ^%ZIS A PI and res tores the home devic e.
	3611	Do not iss ue a form feed when calling ^% ZISC. The Device Han dler takes care of i ssuing a f orm feed i f necessar y (i.e., i f $Y>0, in dicating t he cursor or print h ead is not at the to p of form) . To preve nt the Dev ice Handle r from iss uing this form feed, as approp riate for continuous printing of labels, for examp le, define the IONOF F input va riable bef ore callin g ^%ZISC.
	3612	Before the ^%ZISC AP I existed, close log ic was exe cuted with the comma nd X ^%ZIS (“C”). Dev elopers ha ve been ad vised that X ^%ZIS(“ C”) is no longer sup ported and that the ^%ZISC API should be used inst ead. In th e current version of Kernel, t he ^%ZIS(“ C”) node o nly holds a call to the ^%ZISC routine. Kernel ver sions beyo nd Kernel 8.0 will n ot export ^%ZIS(“C”) .
	3613	Format:^%Z ISC
	3614	Make sure to perform the follo wing steps before ca lling this API:
	3615	NEW all no n-namespac ed variabl es.
	3616	Set all in put variab les.
	3617	Call the A PI.
	3618	Input Vari ables:See ^%ZIS:For a list of input vari ables, see the norma l device o utput vari ables from the ^%ZIS : Standard Device Ca ll API.
	3619	Output Var iables:See ^%ZIS:For a list of output va riables, s ee the nor mal device output va riables fr om the ^%Z IS: Standa rd Device Call API.
	3620
	3621	Example
	3622	>D ^%ZISC
	3623
	3624	PKILL^%ZIS P: Kill Sp ecial Prin ter Variab les
	3625	Reference Type:Suppo rted
	3626	Category:D evice Hand ler
	3627	ICR #:3172
	3628	Descriptio n:This API KILLs pri nter-speci fic Device Handler v ariables. All output parameter s defined by the PSE T^%ZISP: S et Up Spec ial Printe r Variable s API are KILLed.
	3629	Format:PKI LL^%ZISP
	3630	Input Para meters:non e.
	3631	Output:non e.
	3632
	3633	PSET^%ZISP : Set Up S pecial Pri nter Varia bles
	3634	Reference Type:Suppo rted
	3635	Category:D evice Hand ler
	3636	ICR #:3172
	3637	Descriptio n:This API defines a set of va riables th at toggle special pr inter mode s. The cor responding fields in the TERMI NAL TYPE f ile (#3.2) entry for the termi nal type i n question must be c orrectly s et up, how ever; that is where PSET^%ZISP retrieves its outpu t values.
	3638	Format:PSE T^%ZISP
	3639	Make sure to perform the follo wing steps before ca lling this API:
	3640	NEW all no n-namespac ed variabl es.
	3641	Set all in put variab les.
	3642	Call the A PI.
	3643	Input Vari ables:IOST (0):(requi red) Point er to the TERMINAL T YPE entry for the pr inter in q uestion, a s set up b y the Devi ce Handler .
	3644	Output Var iables:IOB AROFF:Bar code off.
	3645	IOBARON:Ba r code on.
	3646	IOCLROFF:C olor off.
	3647	IOCLRON:Co lor on.
	3648	IODPLXL:Du plex, long edge bind ing.
	3649	IODPLXS:Du plex, shor t edge bin ding.
	3650	IOITLOFF:I talics off .
	3651	IOITLON:It alics on.
	3652	IOSMPLX:Si mplex.
	3653	IOSPROFF:S uperscript off.
	3654	IOSPRON:Su perscript on.
	3655	IOSUBOFF:S ubscript o ff.
	3656	IOSUBON:Su bscript on .
	3657
	3658	Example
	3659	To toggle a printer mode with one of PSE T^%ZISP’s output var iables, WR ITE the va riable to the printe r using in direction, as follow s:
	3660	>D PSET^%Z ISP
	3661	>W @IOBARO N
	3662
	3663	ENDR^%ZISS : Set Up S pecific Sc reen Handl ing Variab les
	3664	Reference Type:Suppo rted
	3665	Category:D evice Hand ler
	3666	ICR #:1008 8
	3667	Descriptio n:This API sets up s pecific sc reen-handl ing variab les and ot her termin al type at tributes. Unlike the ENS^%ZISS : Set Up S creen-hand ling Varia bles API, which sets up all sc reen-handl ing variab les, you s pecify whi ch ones to set up wi th ENDR^%Z ISS.
	3668	Format:END R^%ZISS
	3669	Make sure to perform the follo wing steps before ca lling this API:
	3670	NEW all no n-namespac ed variabl es.
	3671	Set all in put variab les.
	3672	Call the A PI.
	3673	Input Vari ables:IOST (0):(requi red) Inter nal entry number (IE N) of the selected d evice’s su btype as r ecorded in the TERMI NAL TYPE f ile (#3.2) .
	3674	X:(require d) Use thi s input va riable to select the ENS^%ZISS screen-ha ndling var iables to define. It should be a semicol on-delimit ed list of the varia bles to de fine. For example:
	3675	>S X=“IORV ON;IORVOFF ;IOUON;IOU OFF”
	3676	If more th an 255 cha racters ar e needed t o define t he X varia ble, make two or mor e calls to ENDR^%ZIS S, each wi th a parti al list of the varia ble settin gs for X.
	3677	%ZIS:(opti onal) If y ou define %ZIS=“I”, the output array IOI S is creat ed. The fo rmat of IO IS is as f ollows:
	3678	IOIS(ASCII value of first char acter foll owed by re maining ch aracters)= output var iable
	3679	For exampl e:
	3680	IOIS(“27[C ”)=IOCUF
	3681	Not every screen-han dling vari able has a correspon ding IOIS node. Also , only the nodes in the IOIS a rray that correspond to screen -handling variables specified in the X i nput varia ble are cr eated.
	3682	Output Var iables:See ENS^%ZISS :A subset of the out put variab les return ed by ENS^ %ZISS: Set Up Screen -handling Variables API are re turned by ENDR^%ZISS , dependin g on what screen-han dling vari ables are requested in the x i nput varia ble.
	3683
	3684	ENS^%ZISS: Set Up Sc reen-handl ing Variab les
	3685	Reference Type:Suppo rted
	3686	Category:D evice Hand ler
	3687	ICR #:1008 8
	3688	Descriptio n:This is a screen m anagement API. It se ts up scre en handlin g variable s and othe r terminal type attr ibutes.
	3689	Format:ENS ^%ZISS
	3690	Make sure to perform the follo wing steps before ca lling this API:
	3691	NEW all no n-namespac ed variabl es.
	3692	Set all in put variab les.
	3693	Call the A PI.
	3694	Input Vari ables:IOST (0):(requi red) Inter nal entry number of the select ed device’ s subtype as recorde d in the T ERMINAL TY PE file (# 3.2).
	3695	%ZIS:(opti onal) If y ou define %ZIS = “I” , the outp ut array I OIS (mappi ng escape codes sent by input keys to in put keys) is created .
	3696	REF: For a descripti on of the IOIS nodes created, see the “O utput Vari ables” sec tion below .
	3697	NOTE: Not all charac teristics are possib le on all terminal t ypes for a ll output variables. The IOEFL D and IOST BM variabl es are use d with ind irection. Also, IOST BM require s the sett ing of IOT M and IOBM as input variables for the to p and bott om margins .
	3698	Output Var iables:IOA RM0:Auto r epeat mode off.
	3699	IOARM1:Aut o repeat m ode on.
	3700	IOAWM0:Aut o wrap mod e off.
	3701	IOAWM1:Aut o wrap mod e on.
	3702	IOBOFF:Bli nk off.
	3703	IOBON:Blin k on.
	3704	IOCOMMA:Ke ypad’s com ma.
	3705	IOCUB:Curs or backwar d.
	3706	IOCUD:Curs or down.
	3707	IOCUF:Curs or forward .
	3708	IOCUON:Cur sor on.
	3709	IOCUOFF:Cu rsor off.
	3710	IOCUU:Curs or up.
	3711	IODCH:Dele te charact er.
	3712	IODHLB:Dou ble-high/w ide bottom .
	3713	IODHLT:Dou ble-high/w ide top.
	3714	IODL:Delet e line.
	3715	IODWl:Doub lewide len gth.
	3716	IOECH:Eras e characte r.
	3717	IOEDALL:Er ase in dis play entir e page.
	3718	IOEDBOP:Er ase in dis play from beginning of page to cursor.
	3719	IOEDEOP:Er ase in dis play from cursor to end of pag e.
	3720	IOEFLD:Era se field ( *use throu gh indirec tion, such as, W @IO EFLD).
	3721	IOELALL:Er ase in lin e entire l ine.
	3722	IOELBOL:Er ase in lin e from beg inning of line to cu rsor.
	3723	IOELEOL:Er ase in lin e from cur sor to end of line.
	3724	IOENTER:Ke ypad’s Ent er.
	3725	IOFIND:Fin d key.
	3726	IOHDWN:Hal f down.
	3727	IOHOME:Hom e cursor.
	3728	IOHTS:Hori zontal tab set.
	3729	IOHUP:Half up.
	3730	IOICH:Inse rt charact er.
	3731	IOIL:Inser t line.
	3732	IOIND:Inde x.
	3733	IOINHI:Hig h intensit y.
	3734	IOINLOW:Lo w intensit y.
	3735	IOINORM:No rmal inten sity.
	3736	IOINSERT:I nsert key.
	3737	IOKP0:Keyp ad 0.
	3738	IOKP1:Keyp ad 1.
	3739	IOKP2:Keyp ad 2.
	3740	IOKP3:Keyp ad 3.
	3741	IOKP4:Keyp ad 4.
	3742	IOKP5:Keyp ad 5.
	3743	IOKP6:Keyp ad 6.
	3744	IOKP7:Keyp ad 7.
	3745	IOKP8:Keyp ad 8.
	3746	IOKP9:Keyp ad 9.
	3747	IOIRM0:Rep lace mode.
	3748	IOIRM1:Ins ert mode.
	3749	IOKPAM:Key pad applic ation mode on.
	3750	IOKPNM:Key pad numeri c mode on.
	3751	IOMC:Print screen.
	3752	IOMINUS:Ke ypad’s min us.
	3753	IONEL:Next line.
	3754	IONEXTSC:N ext screen .
	3755	IOPERIOD:K eypad’s pe riod.
	3756	IOPF1:Func tion key 1 .
	3757	IOPF2:Func tion key 2 .
	3758	IOPF3:Func tion key 3 .
	3759	IOPF4:Func tion key 4 .
	3760	IOPREVSC:P revious sc reen.
	3761	IOPROP:Pro portional spacing.
	3762	IOPTCH10:1 0 Pitch.
	3763	IOPTCH12:1 2 Pitch.
	3764	IOPTCH16:1 6 Pitch.
	3765	IORC:Resto re cursor.
	3766	IOREMOVE:K eypad’s Re move.
	3767	IORESET:Re set.
	3768	IORI:Rever se index.
	3769	IORLF:Reve rse line f eed.
	3770	IORVOFF:Re verse vide o off.
	3771	IORVON:Rev erse video on.
	3772	IOSC:Save cursor.
	3773	IOSGR0:Tur n off sele ct graphic rendition attribute s.
	3774	IOSELECT:K eypad’s Se lect.
	3775	IOSTBM:Set top and b ottom marg ins (*use through in direction, such as, W @IOSTBM; IOTM and IOBM must be defined as the to p and bott om margins ).
	3776	IOSWL:Sing lewide len gth.
	3777	IOTBC:Tab clear.
	3778	IOTBCALL:C lear all t abs.
	3779	IOUOFF:Und erline off .
	3780	IOUON:Unde rline on.
	3781	IOIS:This array is c reated as follows:
	3782	IOIS(escap e_code)=KE YNAME
	3783	Where esca pe_code is the escap e code gen erated by pressing t he key KEY NAME on th e selected terminal, and KEYNA ME can be one of the following :
	3784	COMMA
	3785	DO
	3786	ENTER
	3787	FIND
	3788	HELP
	3789	INSERT
	3790	IOCUB
	3791	IOCUD
	3792	IOCUF
	3793	IOCUU
	3794	KP0
	3795	KP1
	3796	KP2
	3797	KP3
	3798	KP4
	3799	KP5
	3800	KP6
	3801	KP7
	3802	KP8
	3803	KP9
	3804	MINUS
	3805	NEXTSCRN
	3806	PERIOD
	3807	PF1
	3808	PF2
	3809	PF3
	3810	PF4
	3811	PREVSCRN
	3812	REMOVE
	3813	SELECT
	3814
	3815	GKILL^%ZIS S: KILL Gr aphic Vari ables
	3816	Reference Type:Suppo rted
	3817	Category:D evice Hand ler
	3818	ICR #:1008 8
	3819	Descriptio n:This is a screen m anagement API. It KI LLs graphi c variable s used in screen han dling. All output pa rameters s et up by t he GSET^%Z ISS: Set U p Graphic Variables API are KI LLed.
	3820	Format:GKI LL^%ZISS
	3821	Input Para meters:non e.
	3822	Output:non e.
	3823
	3824	GSET^%ZISS : Set Up G raphic Var iables
	3825	Reference Type:Suppo rted
	3826	Category:D evice Hand ler
	3827	ICR #:1008 8
	3828	Descriptio n:This is a screen m anagement API. It se ts up grap hic variab les for sc reen handl ing. Graph ics on/off is a togg le that re maps chara cters for use as gra phics. Not all termi nals need remapping, since the y already have the h igh range of ASCII c odes.
	3829	Format:GSE T^%ZISS
	3830	Make sure to perform the follo wing steps before ca lling this API:
	3831	NEW all no n-namespac ed variabl es.
	3832	Set all in put variab les.
	3833	Call the A PI.
	3834	Input Vari ables:IOST (0):(requi red) Termi nal Type.
	3835	Output Var iables:IOB LC:Bottom left corne r.
	3836	IOBRC:Bott om right c orner.
	3837	IOBT:Botto m “T”.
	3838	IOG1:Graph ics on.
	3839	IOG0:Graph ics off.
	3840	IOHL:Horiz ontal line .
	3841	IOLT:Left “T”.
	3842	IOMT:Middl e “T”, or cross hair (“+”).
	3843	IORT:Right “T”.
	3844	IOTLC:Top left corne r.
	3845	IOTRC:Top right corn er.
	3846	IOTT:Top “ T”.
	3847	IOVL:Verti cal line.
	3848
	3849	Example
	3850	Figure 25: GSET^%ZIS S API—Exam ple
	3851	; write a horizontal line
	3852	D GSET^%ZI SS
	3853	W IOG1
	3854	F I=1:1:20 W IOHL
	3855	W IOG0
	3856	D GKILL^%Z ISS
	3857
	3858	KILL^%ZISS : KILL Scr een Handli ng Variabl es
	3859	Reference Type:Suppo rted
	3860	Category:D evice Hand ler
	3861	ICR #:1008 8
	3862	Descriptio n:This is a screen m anagement API. It KI LLs graphi c variable s used in screen han dling. Onl y the outp ut paramet ers set up by the EN S^%ZISS: S et Up Scre en-handlin g Variable s and ENDR ^%ZISS: Se t Up Speci fic Screen Handling Variables APIs are K ILLed by t his call.
	3863	Format:KIL L^%ZISS
	3864	Input Para meters:non e.
	3865	Output:non e.
	3866
	3867	CALL^%ZIST CP: Make T CP/IP Conn ection (Re mote Syste m)
	3868	Reference Type:Suppo rted
	3869	Category:D evice Hand ler
	3870	ICR #:2118
	3871	Descriptio n:This API makes a T CP/IP conn ection to a remote s ystem.
	3872	NOTE: This API is IP v6 complia nt.
	3873	Format:CAL L^%ZISTCP
	3874	Make sure to perform the follo wing steps before ca lling this API:
	3875	NEW all no n-namespac ed variabl es.
	3876	Set all in put variab les.
	3877	Call the A PI.
	3878	Input Vari ables:IPAD DRESS:(req uired) Thi s is the I nternet Pr otocol (IP ) address of the Hos t system t o which it connects. It must b e in the I Pv4 format of four n umbers sep arated by dots (e.g. , 99.99.9. 999) or IP v6 format (e.g., fe8 0::206a:b2 1b:fbd5:c9 3).
	3879	SOCKET:(re quired) Th is is the socket to connect to on the re mote host. It is an integer fr om 1-65535 . Values b elow 5000 are reserv ed for sta ndard Inte rnet servi ces (e.g., SMTP mail ).
	3880	TIMEOUT:(o ptional) T his is the timeout t o apply to the Open.
	3881	Output Var iables:IO: If the con nection is made then the IO va riable hol ds the imp lementatio n value th at referen ces the co nnection.
	3882	POP:This o utput vari able repor ts the con nection st atus:
	3883	Successful —A value o f zero (0) means the connectio n was succ essful.
	3884	Unsuccessf ul—A posit ive value means the connection failed.
	3885	It works t he same as a call to the ^%ZIS : Standard Device Ca ll API.
	3886
	3887	CLOSE^%ZIS TCP: Close TCP/IP Co nnection ( Remote Sys tem)
	3888	Reference Type:Suppo rted
	3889	Category:D evice Hand ler
	3890	ICR #:2118
	3891	Descriptio n:This API closes th e connecti on opened with the C ALL^%ZISTC P: Make TC P/IP Conne ction (Rem ote System ) API. It works like a call to the ^%ZIS C: Close D evice API.
	3892	NOTE: This API is IP v6 complia nt.
	3893	Format:CLO SE^%ZISTCP
	3894	Make sure to perform the follo wing steps before ca lling this API:
	3895	NEW all no n-namespac ed variabl es.
	3896	Set all in put variab les.
	3897	Call the A PI.
	3898	Input Vari ables:See CALL^%ZIST CP:For a l ist of inp ut variabl es, see CA LL^%ZISTCP : Make TCP /IP Connec tion (Remo te System) API.
	3899	Output Var iables:See CALL^%ZIS TCP:For a list of ou tput varia bles, see CALL^%ZIST CP: Make T CP/IP Conn ection (Re mote Syste m) API.
	3900
	3901	CLOSE^%ZIS UTL(): Clo se Device with Handl e
	3902	Reference Type:Suppo rted
	3903	Category:D evice Hand ler
	3904	ICR #:2119
	3905	Descriptio n:This API closes a device ope ned with t he OPEN^%Z ISUTL(): O pen Device with Hand le API. Wh en you clo se a devic e with CLO SE^%ZISUTL , the IO v ariables a re set bac k to the h ome device ’s and the home devi ce is made the curre nt device. One of th ree functi ons that s upport usi ng multipl e devices at the sam e time.
	3906	REF: See a lso OPEN^% ZISUTL(): Open Devic e with Han dle and US E^%ZISUTL( ): Use Dev ice Given a Handle A PIs.
	3907	Format:CLO SE^%ZISUTL (handle)
	3908	Input Para meters:han dle:(requi red) The h andle of a device op ened with the OPEN^% ZISUTL(): Open Devic e with Han dle API.
	3909	Output:non e.
	3910
	3911	OPEN^%ZISU TL(): Open Device wi th Handle
	3912	Reference Type:Suppo rted
	3913	Category:D evice Hand ler
	3914	ICR #:2119
	3915	Descriptio n:Use this API when you expect to be usi ng multipl e output d evices. Th is API, as well as i ts two com panion API s: RMDEV^% ZISUTL(): Delete Dat a Given a Handle and CLOSE^%ZI SUTL(): Cl ose Device with Hand le, makes use of han dles to re fer to a d evice. A h andle is a unique st ring ident ifying the device.
	3916	The three ^%ZISUTL A PIs are es sentially wrappers a round the ^%ZIS API. They prov ide enhanc ed managem ent of IO variables and the cu rrent devi ce, especi ally when working wi th multipl e open dev ices. One of three f unctions t hat suppor t using mu ltiple dev ices at th e same tim e.
	3917	REF: See a lso RMDEV^ %ZISUTL(): Delete Da ta Given a Handle an d CLOSE^%Z ISUTL(): C lose Devic e with Han dle APIs.
	3918	Format:OPE N^%ZISUTL( handle[,va liop][,.va lzis])
	3919	Input Para meters:han dle:(requi red) A uni que FREE T EXT name t o associat e with a d evice you want to op en.
	3920	valiop:(op tional) Ou tput devic e specific ation, in the same f ormat as t he IOP inp ut variabl e for the ^%ZIS: Sta ndard Devi ce Call AP I. The one exception to this i s passing a value of NULL; thi s is like leaving IO P undefine d. With ^% ZIS, on th e other ha nd, settin g IOP to N ULL specif ies the ho me device. To reques t the home device, p ass a valu e of “HOME ” instead.
	3921	.valzis:(o ptional) I nput speci fication a rray, in t he same fo rmat (and with the s ame meanin gs) as the %ZIS inpu t specific ation arra y for the ^%ZIS: Sta ndard Devi ce Call AP I. Must be passed by reference .
	3922	REF: For m ore inform ation, see the ^%ZIS function documentat ion.
	3923	Output Var iables:IOF :OPEN^%ZIS UTL return s all the same outpu t variable s as the ^ %ZIS: Stan dard Devic e Call API . OPEN^%ZI SUTL serve s as a “wr apper” aro und the ^% ZIS: Stand ard Device Call API, providing additiona l manageme nt of IO o utput vari ables that ^%ZIS doe s not (pri ncipally t o support opening mu ltiple dev ices simul taneously) .
	3924	REF: For m ore inform ation on t hese varia bles, see the ^%ZIS documentat ion.
	3925	IOM
	3926	IOSL
	3927	IO
	3928	IO(0)
	3929	IO(“Q”)
	3930	IO(“S”)
	3931	IO(“DOC”)
	3932	IO(“SPOOL” )
	3933	IO(“ZIO”)
	3934	IO(“HFSIO” )
	3935	IO(1,$I)
	3936	IOST
	3937	IOST(0)
	3938	IOT
	3939	ION
	3940	IOBS
	3941	IOPAR
	3942	IOUPAR
	3943	IOS
	3944	IOHG
	3945	IOXY
	3946	POP
	3947
	3948	Example
	3949	Figure 26: OPEN^%ZIS UTL API—Ex ample
	3950	ZXGTMP ; ISC-SF/doc %ZISUTL s ample ;11- oct-94
	3951	;; 1.0;;
	3952	EN ;
	3953	K A6AZIS S A 6AZIS(“A”) =“Enter th e printer to output first 40 c hars in ea ch line: ”
	3954	D OPEN^%ZISU TL(“PRT1”, “”,.A6AZIS ) Q:POP
	3955	K A6AZIS S A 6AZIS(“A”) =“Enter th e printer to output chars 41
	3956	to end of line: ”
	3957	D OPEN^%ZISU TL(“PRT2”, “”,.A6AZIS ) I POP D CLOSE^%ZIS UTL(“PRT1” ) Q
	3958	S I=“” F S I=$O(^TMP ($J,“DOC”, I)) Q:I’]“ ” S X=^(I ) D
	3959	.D USE^%ZISU TL(“PRT1”) U IO W $E (X,1,40),!
	3960	.D USE^%ZISU TL(“PRT2”) U IO W $E (X,41,$L(X )),!
	3961	D CLOSE^%ZIS UTL(“PRT1” ),CLOSE^%Z ISUTL(“PRT 2”)
	3962	Q
	3963
	3964	RMDEV^%ZIS UTL(): Del ete Data G iven a Han dle
	3965	Reference Type:Suppo rted
	3966	Category:D evice Hand ler
	3967	ICR #:2119
	3968	Descriptio n:This API deletes t he data as sociated w ith the ha ndle. It d oes not ch ange any o f the IO* variables.
	3969	Format:RMD EV^%ZISUTL (handle)
	3970	Input Para meters:han dle:(requi red) A uni que Free T ext name t o associat e with a d evice that you want to delete.
	3971	Output:non e.
	3972
	3973	SAVDEV^%ZI SUTL(): Sa ve Data Gi ven a Hand le
	3974	Reference Type:Suppo rted
	3975	Category:D evice Hand ler
	3976	ICR #:2119
	3977	Descriptio n:This API saves the current d evice IO* variables under the handle nam e.
	3978	Format:SAV DEV^%ZISUT L(handle)
	3979	Input Para meters:han dle:(requi red) A uni que Free T ext name t o associat e with a d evice that you want to save.
	3980	Output:non e.
	3981
	3982	USE^%ZISUT L(): Use D evice Give n a Handle
	3983	Reference Type:Suppo rted
	3984	Category:D evice Hand ler
	3985	ICR #:2119
	3986	Descriptio n:This API restores the IO var iables for a device saved with the OPEN^ %ZISUTL(): Open Devi ce with Ha ndle or SA VDEV^%ZISU TL(): Save Data Give n a Handle APIs. It then does a USE of t he device if it is o pen. The s ame as:
	3987	>DO USE^%Z ISUTL(hand le) U IO
	3988	REF: See a lso OPEN^% ZISUTL(): Open Devic e with Han dle and CA LL^%ZISTCP : Make TCP /IP Connec tion (Remo te System) APIs.
	3989	Format:USE ^%ZISUTL(h andle)
	3990	Input Para meters:han dle:(requi red) A uni que Free T ext name t o associat e with the device th at was ope ned with t he OPEN^%Z ISUTL(): O pen Device with Hand le API.
	3991	Output Var iables:IO* :Standard IO variabl es.
	3992
	3993	Special De vice Issue s
	3994	This secti on discuss es the fol lowing spe cial devic es and dev ice issues :
	3995	Form Feeds
	3996	Resources
	3997	Form Feeds
	3998	The Device Handler h as a metho d for issu ing a form feed at t he point w hen it clo ses the de vice. The purpose fo r this uti lity is to eliminate unnecessa ry page fe eds at the beginning or end of a report. Extra pag e feeds re sult when an applica tion issue s its own form feed at the beg inning of a report a nd then VA FileMan i ssues anot her pair, one at the beginning and one a t the end. An additi onal probl em is lase r printers that also generate an extra f orm feed t o clear th e print bu ffer.
	3999	When closi ng a devic e, ^%ZISC checks the value of $Y to dete rmine the cursor or print head ’s vertica l line loc ation. If $Y is grea ter than z ero, the D evice Hand ler WRITEs a form fe ed (W @IOF ) to reset the value of $Y to zero. Ther efore, app lications should not issue any form feed s when cal ling the D evice Hand ler to ope n or close a device.
	4000	VA FileMan has alrea dy removed its initi al form fe ed. For th e benefit of those w ho use VA FileMan wi thout Kern el and its Device Ha ndler, VA FileMan co ntinues to issue a f orm feed a t the end when the d evice is c losed. Sin ce this pr ocedure re sets the $ Y special variable t o zero, th e Device H andler doe s not send an additi onal form feed when VA FileMan is used w ith Kernel .
	4001	Device Han dler also checks for the exist ence of th e IONOFF v ariable wh en closing the devic e. Thus, a pplication developer s can use the IONOFF variable to suppres s form fee ds by sett ing it jus t before c alling ^%Z ISC: Close Device AP I to close the devic e.
	4002	How to Che ck if Curr ent Device is a CRT
	4003	You should use the f ollowing c ode to tes t if the c urrent dev ice is a C RT (if it returns fa lse, the c urrent dev ice is a C RT; if it returns tr ue, you sh ould assum e that the current d evice is a printer):
	4004	>I $E(IOST ,1,2)’=“C- ”
	4005	Guidelines for Form Issuing Fo rm Feeds
	4006	In most ca ses, a for m feed bef ore the fi rst page i s only nee ded for re ports to C RTs. When directing reports to a printer , do not i ssue an in itial form feed befo re the fir st page; i t is not n eeded. How ever, you should pri nt the hea ding (if u sed) on th e first pa ge. You do need to i ssue a for m feed bet ween pages , regardle ss of whet her the re port is di rected to a CRT or t o a printe r.
	4007	The follow ing summar izes the c urrent gui delines fo r issuing form feeds for CRTs and printe rs:
	4008	CRTs
	4009	Issue the initial fo rm feed be fore the f irst page of a repor t as befor e.
	4010	Print a he ading on t he first p age if hea dings are used.
	4011	Print the lines of t he report while chec king the v alue of th e vertical position ($Y).
	4012	If there i s no more data to pr ocess, the n GO TO ST EP #9.
	4013	If the val ue of the vertical p osition pl us a prede termined n umber to s erve as a buffer exc eeds the s creen leng th, prompt the user to press < Enter> to continue.
	4014	A time-out at the RE AD or a ca ret (“^”) response t o the cont inue promp t represen ts a reque st to term inate the display. G O TO STEP 9.
	4015	If the use r presses <Enter> in response to the pro mpt, issue a form fe ed followe d by a hea ding (if u sed).
	4016	GO TO STEP 3.
	4017	The applic ation shou ld termina te the dis play of th e report.
	4018	END.
	4019	Printers
	4020	Do not iss ue a form feed befor e the firs t page of a report.
	4021	Print a he ading on t he first p age if hea dings are used.
	4022	Print the lines of t he report while chec king the v alue of th e vertical position ($Y).
	4023	If there i s no more data to pr ocess, the n GO TO ST EP 7.
	4024	If the val ue of the vertical p osition pl us a prede termined n umber to s erve as a buffer exc eeds the p age line l imit, issu e a form f eed.
	4025	GO TO STEP 3.
	4026	The applic ation shou ld termina te the pri ntout of t he report.
	4027	END.
	4028	The sample routines Figure 27 and Figure 28 provid e two exam ples of ho w to outpu t a report following current g uidelines for form f eeds. In t he example s, a serie s of three vertical dots indic ates omitt ed informa tion.
	4029	Figure 27: Device Ha ndler—Issu ing form f eeds follo wing curre nt guideli nes
	4030	ROU ; SAMPLE ROU TINE
	4031	S IOP=“DEVN AM” D ^%ZI S G EXIT:P OP
	4032	I $D(IO(“Q” )) S ZTRTN =“DQ^ROU”, ZTDESC=“SA MPLE REPOR T” D ^%ZTL OAD,HOME^% ZIS Q
	4033	.
	4034	.
	4035	.
	4036	DQ ; SAMPLE REP ORT
	4037	S (END,PAGE )=0
	4038	U IO D @(“H DR”_(2-($E (IOST,1,2) =“C-”))) F Q:END D
	4039	. W !,....
	4040	. W !,...
	4041	. D HDR:$Y+5 >IOSL Q
	4042	.
	4043	.
	4044	.
	4045	D ^%ZISC Q
	4046	HDR ; SAMPLE HEA DER
	4047	I $E(IOST,1 ,2)=“C-” W !,“Press RETURN to continue o r ‘^’ to e xit: ” R X :DTIME S E ND=‘$T!(X= “^”) Q:END
	4048	HDR1 W @IOF
	4049	HDR2 S PAGE=PAGE +1 W ?20,“ SAMPLE HEA DING”,?(IO M-10),“PAG E: ”,$J(P AGE,3)
	4050
	4051	Figure 28: Device Ha ndler—Alte rnate appr oach follo wing curre nt guideli nes
	4052	ROU ; SAMPLE ROU TINE
	4053	S IOP=“DEVN AM” D ^%ZI S G EXIT:P OP
	4054	I $D(IO(“Q” )) S ZTRTN =“DQ^ROU”, ZTDESC=“SA MPLE REPOR T” D ^%ZTL OAD,HOME^% ZIS Q
	4055	.
	4056	.
	4057	.
	4058	DQ ; SAMPLE REP ORT
	4059	S (END,PAGE )=0
	4060	U IO F Q:E ND D
	4061	. D HDR:$Y+5 >IOSL Q
	4062	. W !,....
	4063	. W !,...
	4064	.
	4065	.
	4066	.
	4067	D ^%ZISC Q
	4068	HDR ; SAMPLE HEA DER
	4069	I PAGE,$E(I OST,1,2)=“ C-” W !,“P ress RETUR N to conti nue or ‘^’ to exit: ” R X:DTIM E S END=‘$ T!(X=“^”) Q:END
	4070	HDR1 W :’($E(IOST ,1,2)’=“C- ”&’PAGE) @ IOF
	4071	HDR2 S PAGE=PAGE +1 W ?20,“ SAMPLE HEA DING”,?(IO M-10),“PAG E: ”,$J(P AGE,3)
	4072
	4073	Resources
	4074	Queuing to a Resourc e
	4075	You can on ly use res ources thr ough calls to ^%ZTLO AD. They c annot be d irectly ma nipulated (except by TaskMan). To use a resource, you need t o set the ZTIO input variable to the nam e of the r esource. F or example :
	4076	>S ZTIO=“Z ZRES”,ZTRT N=“tag^rou tine”,ZTDT H=$H
	4077	>S ZTDESC= “First tas k in a ser ies”
	4078	>D ^%ZTLOA D
	4079
	4080	Since the name of th e resource is part o f the call , applicat ion develo pers must include in stallation procedure s so that system adm inistrator s are able to create the resou rces using the corre ct names a nd other a ttributes.
	4081	You can op tionally u se a SYNC FLAG when queuing to a Resourc e type dev ice. Using a SYNC FL AG helps t o ensure t hat sequen tial tasks queued to a resourc e only run if the pr eceding ta sk in the series has completed successfu lly.
	4082	REF: For m ore inform ation on u sing SYNC FLAGs, see the “Task Man: Devel oper Tools ” section.
	4083
	4084
	4085	Domain Nam e Service (DNS): Dev eloper Too ls
	4086	Applicatio n Programm ing Interf ace (API)
	4087	Several AP Is are ava ilable for developer s to work with Domai n Name Ser vice (DNS) . These AP Is are des cribed bel ow.
	4088	$$ADDRESS^ XLFNSLK(): Convert D omain Name to IP Add resses
	4089	Reference Type:Suppo rted
	4090	Category:D omain Name Service ( DNS)
	4091	ICR #:3056
	4092	Descriptio n:This ext rinsic fun ction call s the Doma in Name Se rvice (DNS ) to conve rt a domai n name int o its IP a ddresses. The IP add resses of the DNS be ing called are in th e DNS IP f ield (#898 9.3,51) in the KERNE L SYSTEM P ARAMETERS file (#898 9.3).
	4093	NOTE: This API is IP v6 complia nt.
	4094	Format:$$A DDRESS^XLF NSLK(domai n_name[,ty pe])
	4095	Input Para meters:dom ain_name:( required) This is th e fully qu alified do main name (e.g., FOR UM. D O MAIN ).
	4096	type:(opti onal) This input par ameter is from the s et A: IPv4 address ( the defaul t), AAAA: IPv6 addre ss, CNAME: alias.
	4097	Output:ret urns:Retur ns a comma -separated list of I P addresse s that are associate d with the input dom ain.
	4098
	4099	Examples
	4100	>S X=$$ADD RESS^XLFNS LK(“FORUM. D O MAIN ”)
	4101
	4102	>W X
	4103	99.9.99.99 9
	4104
	4105	>S X=$$ADD RESS^XLFNS LK(“www.go ogle.com”, “AAAA” )
	4106
	4107	>W X
	4108	2607:F8B0: 400E:0C02: 0000:0000: 0000:0067
	4109
	4110	MAIL^XLFNS LK(): Get IP Address es for a D omain Name
	4111	Reference Type:Suppo rted
	4112	Category:D omain Name Service ( DNS)
	4113	ICR #:3056
	4114	Descriptio n:This API calls the Domain Na me Service (DNS) to get the MX records f or a domai n name wit h its IP a ddresses.
	4115	NOTE: This API is IP v6 complia nt.
	4116	Format:MAI L^XLFNSLK( .return,do main_name)
	4117	Input Para meters:.re turn:(requ ired) A lo cal variab le passed by referen ce to hold the retur n array.
	4118	domain_nam e:(require d) This pa rameter is a fully q ualified d omain name (e.g., FO RUM. D O MAIN ).
	4119	Output Par ameters:.r eturn:Retu rns data i n the arra y passed i n by refer ence. The data is su bscripted by priorit y. The dom ain_name p arameter i s a fully qualified domain nam e (e.g., F ORUM. D O MAIN ).
	4120	Examples
	4121	IPv4 Examp le
	4122	>K ZX D MA IL^XLFNSLK (.ZX,“ISC- SF.MED. D O MAIN ”) ZW ZX
	4123	ZX=2
	4124	ZX(5)=a2.I SC-SF.MED. D O MAIN .^99.9.99. 99
	4125	ZX(10)=a1. ISC-SF.MED . D O MAIN .^99.9.99. 99
	4126	IPv6 Examp le
	4127	>K ZX D MA IL^XLFNSLK (.ZX,"GMAI L.COM") ZW ZX
	4128	ZX=5
	4129	ZX(5)="gma il-smtp-in .l.google. COM.^2607: F8B0:4001: 0C0E:0000: 0000:0000: 001A"
	4130	ZX(10)="al t1.gmail-s mtp-in.l.g oogle.COM. ^2607:F8B0 :400D:0C0C :0000:0000 :0000:001B "
	4131	ZX(20)="al t2.gmail-s mtp-in.l.g oogle.COM. ^2607:F8B0 :400C:0C0A :0000:0000 :0000:001B "
	4132	ZX(30)="al t3.gmail-s mtp-in.l.g oogle.COM. ^2A00:1450 :400C:0C08 :0000:0000 :0000:001B "
	4133	ZX(40)="al t4.gmail-s mtp-in.l.g oogle.COM. ^2A00:1450 :400B:0C03 :0000:0000 :0000:001B "
	4134
	4135
	4136
	4137	Electronic Signature s: Develop er Tools
	4138	Applicatio n Programm ing Interf ace (API)
	4139	Several AP Is are ava ilable for developer s to work with elect ronic sign atures. Th ese APIs a re describ ed below.
	4140	^XUSESIG: Set Up Ele ctronic Si gnature Co de
	4141	Reference Type:Contr olled Subs cription
	4142	Category:E lectronic Signatures
	4143	ICR #:936
	4144	Descriptio n:This API , when cal led from t he top, al lows the u ser to set up a pers onal elect ronic sign ature code . It is us ed within applicatio n code to allow the user immed iate on-th e-fly acce ss to set up the ele ctronic si gnature, r ather than force the user to l eave the a pplication and enter a differe nt option to do the same.
	4145	Format:^XU SESIG
	4146	Input Para meters:non e.
	4147	Output:non e.
	4148
	4149	SIG^XUSESI G(): Verif y Electron ic Signatu re Code
	4150	Reference Type:Suppo rted
	4151	Category:E lectronic Signatures
	4152	ICR #:1005 0
	4153	Descriptio n:This API requests and verifi es the ele ctronic si gnature co de of the current us er.
	4154	Format:SIG ^XUSESIG(d uz,x1)
	4155	Input Para meters:duz :(required ) User num ber.
	4156	Output Par ameters:x1 :If the us er entered the corre ct electro nic signat ure code, the encryp ted electr onic signa ture code as stored in the NEW PERSON fi le (#200) is returne d in x1. O therwise, x1 is retu rned as NU LL.
	4157	$$CHKSUM^X USESIG1(): Build Che cksum for Global Roo t
	4158	Reference Type:Suppo rted
	4159	Category:E lectronic Signatures
	4160	ICR #:1557
	4161	Descriptio n:This ext rinsic fun ction take s a global root ($na me_value) and builds a checksu m for all data in th e root.
	4162	NOTE: The flag input parameter is no lon ger used. Previously , It was u sed when t here was m ore than o ne checksu m algorith m.
	4163	Format:$$C HKSUM^XUSE SIG1($name _value[,fl ag])
	4164	Input Para meters:$na me_value:( required) This is a global roo t as would be return ed from $N AME.
	4165	flag:(obso lete) Not used at th is time.
	4166	Output:ret urns:Retur ns the che cksum for the global root.
	4167
	4168	$$CMP^XUSE SIG1(): Co mpare Chec ksum to $N ame_Value
	4169	Reference Type:Suppo rted
	4170	Category:E lectronic Signatures
	4171	ICR #:1557
	4172	Descriptio n:This ext rinsic fun ction comp ares the c hecksum pa ssed in to the calcu lated valu e from the $NAME_VAL UE. It Ret urns the f ollowing:
	4173	1—Match.
	4174	0—No match .
	4175	Format:$$C MP^XUSESIG 1(checksum ,$name_val ue)
	4176	Input Para meters:che cksum:(req uired) The output fr om the $$C HKSUM^XUSE SIG1(): Bu ild Checks um for Glo bal Root A PI.
	4177	$name_valu e:(require d) This is a global root as wo uld be ret urned from $NAME.
	4178	Output:ret urns:Retur ns:
	4179	1—Match.
	4180	0—No match .
	4181
	4182	$$DE^XUSES IG1(): Dec ode String
	4183	Reference Type:Suppo rted
	4184	Category:E lectronic Signatures
	4185	ICR #:1557
	4186	Descriptio n:This ext rinsic fun ction deco des the in put string using the checksum as the key .
	4187	Format:$$D E^XUSESIG1 (checksum, encoded_st ring)
	4188	Input Para meters:che cksum:(req uired) The output fr om the $$C HKSUM^XUSE SIG1(): Bu ild Checks um for Glo bal Root A PI.
	4189	encoded_st ring:(requ ired) The output fro m the $$EN ^XUSESIG1( ): Encode ESBLOCK AP I.
	4190	Output:ret urns:Retur ns the dec oded strin g.
	4191
	4192	$$EN^XUSES IG1(): Enc ode ESBLOC K
	4193	Reference Type:Suppo rted
	4194	Category:E lectronic Signatures
	4195	ICR #:1557
	4196	Descriptio n:This ext rinsic fun ction enco des the ES BLOCK usin g the chec ksum as th e key.
	4197	Format:$$E N^XUSESIG1 (checksum, esblock)
	4198	Input Para meters:che cksum:(req uired) A n umber that reveals i f the data in the ro ot has bee n changed.
	4199	esblock:(o ptional) T his should be the da ta returne d from the $$ESBLOCK ^XUSESIG1( ): E-Sig F ields Requ ired for H ash API.
	4200	Output:ret urns:Retur ns encoded ESBLOCK.
	4201	$$ESBLOCK^ XUSESIG1() : E-Sig Fi elds Requi red for Ha sh
	4202	Reference Type:Suppo rted
	4203	Category:E lectronic Signatures
	4204	ICR #:1557
	4205	Descriptio n:This ext rinsic fun ction retu rns the se t of field s from the NEW PERSO N file (#2 00) that a re needed as part of the hash for an acc eptable el ectronic s ignature ( E-Sig). Th ese fields include t he followi ng:
	4206	E-Sig Bloc k
	4207	E-Sig Titl e
	4208	Degree
	4209	Current Da te/Time
	4210	If the Int ernal Entr y Number ( IEN) is no t passed i n, then it uses the DUZ.
	4211	Format:$$E SBLOCK^XUS ESIG1([ien ])
	4212	Input Para meters:ien :(optional ) This is the Intern al Entry N umber (IEN ) of the N EW PERSON file (#200 ) entry fo r which da ta is requ ested. The default i s to use t he DUZ of the curren t user.
	4213	Output:ret urns:Retur ns the fol lowing fie lds:
	4214	E-Sig Bloc k
	4215	E-Sig Titl e
	4216	Degree
	4217	Current Da te/Time
	4218	DE^XUSHSHP : Decrypt Data Strin g
	4219	Reference Type:Suppo rted
	4220	Category:E lectronic Signatures
	4221	ICR #:1004 5
	4222	Descriptio n:This API decrypts a string e ncrypted b y a call t o the EN^X USHSHP: En crypt Data String AP I. Typical ly, this A PI would b e used to decrypt st rings when printing a document containin g encrypte d strings.
	4223	Format:DE^ XUSHSHP
	4224	Make sure to perform the follo wing steps before ca lling this API:
	4225	NEW all no n-namespac ed variabl es.
	4226	Set all in put variab les.
	4227	Call the A PI.
	4228	Input Vari ables:X:(r equired) E ncrypted s tring gene rated by a call to t he EN^XUSH SHP: Encry pt Data St ring API.
	4229	X1:(requir ed) Identi fication n umber used as the X1 input var iable in t he EN^XUSH SHP: Encry pt Data St ring API.
	4230	X2:(requir ed) Number used as t he X2 inpu t variable in the EN ^XUSHSHP: Encrypt Da ta String API.
	4231	Output Var iables:X:T he decrypt ed string (can be pr inted).
	4232
	4233	EN^XUSHSHP : Encrypt Data Strin g
	4234	Reference Type:Suppo rted
	4235	Category:E lectronic Signatures
	4236	ICR #:1004 5
	4237	Descriptio n:This API encrypts a string, and associ ates the e ncrypted s tring with an identi fication n umber and a document number. T o decrypt the string , a call m ust be mad e to the D E^XUSHSHP: Decrypt D ata String API, with the encry pted strin g, identif ication nu mber, and document n umber as i nput varia bles. Typi cally, thi s API woul d be used to encrypt strings w ithin a do cument.
	4238	Format:EN^ XUSHSHP
	4239	Make sure to perform the follo wing steps before ca lling this API:
	4240	NEW all no n-namespac ed variabl es.
	4241	Set all in put variab les.
	4242	Call the A PI.
	4243	Input Vari ables:X:(r equired) T he string to be encr ypted (e.g ., the con tents of t he SIGNATU RE BLOCK P RINTED NAM E field in the NEW P ERSON file [#200]).
	4244	X1:(requir ed) An ide ntificatio n number ( e.g., DUZ) .
	4245	X2:(requir ed) A docu ment numbe r (or the number one ).
	4246	Output Var iables:X:E ncrypted s tring.
	4247
	4248	HASH^XUSHS HP: Hash E lectronic Signature Code
	4249	Reference Type:Suppo rted
	4250	Category:E lectronic Signatures
	4251	ICR #:1004 5
	4252	Descriptio n:This API uses as i nput the t ext string (signatur e) entered by the us er. The ro utine then hashes th e string. The hashed result ca n then be used to ve rify the u ser’s iden tity by co mparison w ith the st ored elect ronic sign ature code (in the N EW PERSON file [#200 ]).
	4253	Format:HAS H^XUSHSHP
	4254	Make sure to perform the follo wing steps before ca lling this API:
	4255	NEW all no n-namespac ed variabl es.
	4256	Set all in put variab les.
	4257	Call the A PI.
	4258	Input Vari ables:X:(r equired) E lectronic Signature code as en tered by t he user.
	4259	Output Var iables:X:H ashed form of the el ectronic s ignature c ode submit ted as inp ut to func tion.
	4260
	4261
	4262	Error Proc essing: De veloper To ols
	4263	Direct Mod e Utilitie s
	4264	These dire ct mode ut ilities ca n be run f rom Progra mmer mode. They are not, howev er, APIs; instead, t hey are pr ovided for convenien ce.
	4265	>D ^XTER
	4266	You can ca ll the ^XT ER direct mode utili ty from Pr ogrammer m ode. It is the same as using t he Error T rap Displa y option.
	4267	>D ^XTERPU R
	4268	You can ca ll the ^XT ERPUR dire ct mode ut ility from Programme r mode. It is the sa me as usin g the Clea n Error Tr ap option.
	4269	Applicatio n Programm ing Interf ace (API)
	4270	Several AP Is are ava ilable for developer s to work with error processin g. These A PIs are de scribed be low.
	4271	$$EC^%ZOSV : Get Erro r Code
	4272	Reference Type:Suppo rted
	4273	Category:O perating S ystem Inte rface
	4274	ICR #:1009 7
	4275	Descriptio n:This ext rinsic fun ction retu rns the mo st recent error mess age record ed by the operating system.
	4276	Format:$$E C^%ZOSV
	4277	Input Para meters:non e.
	4278	Output:ret urns:Retur ns the mos t recent e rror code/ message.
	4279	Example
	4280	>S X=$$EC^ %ZOSV
	4281
	4282	^%ZTER: Ke rnel Stand ard Error Recording Routine
	4283	Reference Type:Suppo rted
	4284	Category:E rror Proce ssing
	4285	ICR #:1621
	4286	Descriptio n:Kernel s ets the Er ror Trap i n ZU so th at all use r errors a re trapped . In this context, w hen an err or occurs, the optio nal %ZT in put array is set to indicate t he user’s location i n the menu system. T hen ^%ZTER is called to record this info rmation in the ERROR LOG file (#3.075).
	4287	The applic ation-spec ific Error Trap rout ine, when it is call ed as a re sult of an error, ca n then use the ^%ZTE R API to r ecord erro r informat ion in the ERROR LOG file (#3. 075) if it decides t hat it nee ds to. ^%Z TER gather s all avai lable info rmation su ch as loca l symbols and last g lobal refe rence and stores tha t informat ion in an entry in t he ERROR L OG file (# 3.075).
	4288	The simple example b elow shows an applic ation that replaces the standa rd Kernel Error Trap with its own Error Trap. When an error occurs, an d the appl ication’s Error Trap routine i s called, it calls $ $EC^%ZOSV to see wha t type of error occu rred. If a n end-of-f ile (EOF) error occu rs, it let s the appl ication co ntinue. Ot herwise, i t calls ^% ZTER to re cord the e rror, and then quits to termin ate the ap plication.
	4289	NOTE: The recording mechanism of ^%ZTER also funct ions in th e absence of an erro r. In a de bug mode, this would enable a developer to record local symb ols and gl obal struc tures at p redetermin ed places within cod e executio n for late r checking .
	4290	Format:^%Z TER
	4291	Make sure to perform the follo wing steps before ca lling this API:
	4292	NEW all no n-namespac ed variabl es.
	4293	Set all in put variab les.
	4294	Call the A PI.
	4295	Input Vari ables:%ZT: (optional) The %ZT a rray can b e used to identify a global no de whose d escendants should be recorded in the err or log. Wh en called within the standard Kernel Err or Trap, % ZT is set to record the user’s location in the men u system:
	4296	>S %ZT(“^T MP($J)”)=“ ”>D ^%ZTER
	4297	Output Var iables:%ZT ERROR:Call s to the e rror recor der always return th is variabl e. It has the error name and e rror type as its fir st and sec ond caret- delimited (“^”) piec es, for ex ample, %ZT ERROR=UNDE F^P. While the first piece is always def ined since it is ret rieved fro m the oper ating syst em, the se cond piece could be missing if unavailab le from th e ERROR ME SSAGES fil e (#3.076) .
	4298
	4299	Example
	4300	Figure 29 is an exam ple of the Error Tra p:
	4301	Figure 29: Error Tra p—Example
	4302	ZXGP ; 999 /NV - samp le routine ; 23-FEB- 95
	4303	; ;1.0;;
	4304	;
	4305	FILEOPEN;
	4306	;
	4307	; This code resets th e error tr ap routine that is s tepped to
	4308	; when an e rror occur s.
	4309	;
	4310	N $ESTACK,$ ETRAP S $E TRAP=“D ER R^ZXGP”
	4311	;
	4312	; Open a fi le, and re ad lines f rom it unt il End-of- file (EOF)
	4313	; is reache d.
	4314	;
	4315	K %ZIS S %Z IS=“”
	4316	S %ZIS(“HFS NAME”)=“MY FILE.DAT”, %ZIS(“HFSM ODE”)=“RW”
	4317	D ^%ZIS Q:P OP
	4318	F U IO R L INE:DTIME U IO(0) W !,LINE
	4319	;
	4320	FILECLOS;
	4321	;
	4322	D ^%ZISC Q
	4323	;
	4324	ERR ;
	4325	; This is t he applica tion speci fic error trap.
	4326	;
	4327	I $$EC^%ZOS V[“ENDOFIL E” S $ECOD E=“” G FIL ECLOS ; co ntinue if EOF error
	4328	D ^%ZTER ; record the error if anything o ther than EOF
	4329	D UNWIND^%Z TER ; unwi nd the sta ck, return to caller .
	4330	Q
	4331	;
	4332
	4333	$$APPERR^% ZTER: Set Applicatio n Error Na me in Kern el Error T rap Log
	4334	Reference Type:Suppo rted
	4335	Category:E rror Proce ssing
	4336	ICR #:1621
	4337	Descriptio n:This API was added with Kern el patch X U8.0431. It sets t he "applic ation erro r" text pa ssed in as the error name in t he Kernel error trap log (i.e. , ERROR LO G file [#3 .075]).
	4338	NOTE: This API repla ces the ne ed to set $ZE before calling t he ^%ZTER: Kernel St andard Err or Recordi ng Routine API:
	4339	Before:
	4340	>S $ZE=”ap plication error” D ^ %ZTER
	4341	After:
	4342	>D APPERRO R^%ZTER(“a pplication error”)
	4343	Format:APP ERROR^%ZTE R("applica tion error ")
	4344	Input Para meters:“ap plication error”:Thi s input pa rameter is the "appl ication er ror" name that gets displayed in the Ker nel error trap log ( i.e., ERRO R LOG file [#3.075]) .
	4345	Output:ret urns:Displ ays the "a pplication error" te xt passed in as the error name in the Ke rnel error trap log (i.e., ERR OR LOG fil e [#3.075] ).
	4346	Example
	4347	>DO APPERR OR^%ZTER(" My Applica tion Error ")
	4348	Check the Kernel err or trap an d see if t here is an error cal led "My Ap plication Error".
	4349	$$NEWERR^% ZTER: Veri fy Support of Standa rd Error T rapping (O bsolete)
	4350	NOTE: This API is ob solete, be cause all VA systems support t he standar d error tr apping.
	4351	Reference Type:Suppo rted
	4352	Category:E rror Proce ssing
	4353	ICR #:1621
	4354	Descriptio n:This ext rinsic fun ction repo rts if the current p latform su pports the standard error trap ping. It r eturns:
	4355	1—If the s tandard er ror trappi ng is supp orted.
	4356	0—For all other case s.
	4357	Format:$$N EWERR^%ZTE R
	4358	Input Para meters:non e.
	4359	Output:ret urns:Retur ns:
	4360	1—If the s tandard er ror trappi ng is supp orted.
	4361	0—For all other case s.
	4362	UNWIND^%ZT ER: Quit B ack to Cal ling Routi ne
	4363	Reference Type:Suppo rted
	4364	Category:E rror Proce ssing
	4365	ICR #:1621
	4366	Descriptio n:Use this API after a package Error Tra p to quit back to th e calling routine. C ontrol ret urns to th e level ab ove the on e that NEW ED $ESTACK .
	4367	Format:UNW IND^%ZTER
	4368	Input Para meters:non e.
	4369	Output:non e.
	4370	Example
	4371	Main:
	4372	Figure 30: UNWIND^%Z TER API—Ma in code ex ample
	4373	S X=1 D SU B
	4374	W X
	4375	Q SUB N $ESTACK,$ ETRAP S $E TR=“D ERRO R”
	4376	S X=1/0
	4377	Q
	4378
	4379	Usage:
	4380	Figure 31: UNWIND^%Z TER API—Us age
	4381	D ^%ZTER ; This will record the error inf o and clea r $ECODE
	4382	S ^XXX=“In complete r ecord”
	4383	G UNWIND^% ZTER
	4384
	4385
	4386
	4387	Field Moni toring: De veloper To ols
	4388	Applicatio n Programm ing Interf ace (API)
	4389	One API is available for devel opers to w ork with f ield monit oring. Thi s API is d escribed b elow.
	4390	OPKG^XUHUI (): Monito r New Styl e Cross-re ferenced F ields
	4391	Reference Type:Suppo rted
	4392	Category:F ield Monit oring
	4393	ICR #:3589
	4394	Descriptio n:This API allows ot her packag es to task an Option or Protoc ol from a New Style cross-refe rence. Thi s API can be used to monitor a ny field o r fields i n any file using a N ew Style c ross-refer ence.
	4395	Format:OPK G^XUHUI([x uhuiop,]xu huinm[,xuh uia],xuhui xr)
	4396	Input Para meters:xuh uiop:(opti onal) This parameter is a set of Numeric codes tha t tells th e Unwinder to use th e PROTOCOL file (#10 1) or the OPTION fil e (#19). I f this par ameter is null, the default va lue is use d (i.e., “ 101”):
	4397	101 (defau lt)—PROTOC OL file (# 101) is us ed.
	4398	19—The OPT ION file ( #19) is us ed.
	4399	xuhuinm:(r equired) T his parame ter is the NAME (#.0 1) value o f the Prot ocol or Op tion that is to be l aunched.
	4400	xuhuia:(op tional) Th is paramet er is a Se t of Codes . If this input para meter is n ull, the d efault val ue is used (i.e., “S ”):
	4401	S (default )—The data being pas sed is fro m the SETt ing of the cross-ref erence.
	4402	K—The data being pas sed is fro m the KILL ing of the cross-ref erence.
	4403	xuhuixr: ( required) This param eter is th e name of the cross- reference.
	4404	Output:See Example:M onitored f ields with a New Sty le cross-r eference.
	4405	Example
	4406	The Hui Pr oject need s to monit or the fol lowing fie lds at the top level of the NE W PERSON f ile (#200) for chang es in valu e, in the order list ed:
	4407	NAME (#.01 )
	4408	TERMINATIO N DATE (#9 .2)
	4409	DOB (#5)
	4410	SSN (#9)
	4411	Create New Style Cro ss-referen ces
	4412	Create a M UMPS New S tyle cross -reference for the f ields that are to be monitored for value changes, as shown b elow:
	4413	Figure 32: OPKG^XUHU I API—Exam ple of cre ating New Style Cros s-referenc es
	4414	Index Name : AXUHUI ( #n)
	4415
	4416	Short Desc ription: H ui Project Top File Cross-refe rence
	4417
	4418	Desc ription: T his MUMPS New Style cross-refe rence is o n non-mult iple
	4419	f ields in t he NEW PER SON file ( #200) that the Hui P roject
	4420	n eeds to mo nitor for changes in value. T he followi ng fields
	4421	a re being m onitored i n the orde r listed:
	4422
	4423	.01 (NAME)
	4424	9.2 (TERMINAT ION DATE)
	4425	5 ( DOB)
	4426	9 ( SSN)
	4427	F or details on how th is cross-r eference p rocesses c hanges,
	4428	p lease refe r to the p atch descr iption for Kernel Pa tch XU82 36.
	4429	F or more de tailed inf ormation a bout the M UMPS New S tyle
	4430	c ross-refer ence, plea se refer t o the “VA FileMan V. 22.0 Key
	4431	a nd Index T utorial” ( see Lesson s #5 and # 6)
	4432
	4433	Type: MUMPS
	4434
	4435	EXECUTION: RECORD
	4436
	4437	Use: ACTION
	4438
	4439	Set Logic: D OPKG^XUHUI (“”,“XUHUI FIELD CHA NGE EVENT” ,“”,“AXUHU I”) Q
	4440	Kill Logic: Q
	4441	Whole Kill: Q
	4442	X(1): NA ME (200,. 01) (forw ards)
	4443	X(2): TE RMINATION DATE (200 ,9.2) (fo rwards)
	4444	X(3): DO B (200,5) (forward s)
	4445	X(4): SS N (200,9) (forward s)
	4446
	4447	Sample Sce nario
	4448	Change a m onitored ( cross-refe renced) fi eld value in the NEW PERSON fi le (#200), as shown below:
	4449	Figure 33: OPKG^XUHU I API—Samp le scenari o
	4450	INPUT TO W HAT FILE: NEW PERSON // <Enter>
	4451	EDIT WHICH FIELD: AL L// DOB
	4452	THEN EDIT FIELD: SSN
	4453	THEN EDIT FIELD: <En ter>
	4454
	4455	Select NEW PERSON NA ME: XUUSER <Enter> XUUSER,O NE OX
	4456	DOB: JUL 4 ,1950// 12 .24.49 <En ter> (DEC 24, 1949)
	4457	SSN: 00022 0000// 000 558888
	4458
	4459	In this ex ample, the ONE XUUSE R’s Date o f Birth (D OB) was ch anged from 07/04/50 to 12/24/4 9 and also changed t he Social Security N umber (SSN ) from 000 -22-0000 t o 000-55-8 888. Since these fie lds are be ing monito red (i.e., MUMPS New Style cro ss-referen ce, see th e “Create Cross-refe rences” pr evious sec tion), you should se e this dat a passed t o the “XUH UI FIELD C HANGE EVEN T” protoco l (see the “Internal Results f or Develop ers” secti on that fo llows).
	4460	Internal R esults for Developer s
	4461	The follow ing data i s passed t o the “XUH UI FIELD C HANGE EVEN T” Protoco l via the Kernel OPK G^XUHUI AP I that is called in the AXUHUI cross-ref erence (se e the “Cre ate Cross- references ” previous section).
	4462	Figure 34: OPKG^XUHU I API—Exam ple of int ernal resu lts
	4463	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	4464	If executi ng the Kil l logic, t hen the ‘X ’ array wi ll be equa l to the ‘ X1’
	4465	array. If executing the Set l ogic, then the ‘X’ a rray will be equal t o
	4466	the ‘X2’ a rray.
	4467	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	4468	X=XUUSER,O NE
	4469	X(1)=XUUSE R,ONE
	4470	X(2)=
	4471	X(3)=24912 24
	4472	X(4)=00055 8888
	4473	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	4474
	4475	Old values are in th is array.
	4476	Old values are in th is array.
	4477	X1=XUUSER, ONE
	4478	X1(1)=XUUS ER,ONE
	4479	X1(2)=
	4480	X1(3)=2500 704
	4481	X1(4)=0002 20000
	4482	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	4483
	4484	New values are in th is array.
	4485	New values are in th is array.
	4486	X2=XUUSER, ONE
	4487	X2(1)=XUUS ER,ONE
	4488	X2(2)=
	4489	X2(3)=2491 224
	4490	X2(4)=0005 58888
	4491	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	4492
	4493	“S” = Set Logic is b eing execu ted, “K” = Kill logi c being ex ecuted.
	4494	“S” = Set Logic is b eing execu ted, “K” = Kill logi c being ex ecuted.
	4495	XUHUIA=S
	4496	XUHUIDA=70
	4497	XUHUIFIL=2 00
	4498	XUHUIFLD=
	4499
	4500	“DA” array , File num ber, and F ield numbe rs if avai lable.
	4501	“DA” array , File num ber, and F ield numbe rs if avai lable.
	4502	XUHUINM=XU HUI FIELD CHANGE EVE NT
	4503
	4504	Name of Ex tended Act ion entry in File #1 01 or in F ile #19.
	4505	Name of Ex tended Act ion entry in File #1 01 or in F ile #19.
	4506	XUHUIOP=10 1
	4507
	4508	File numbe r of where to find t he Extende d Action.
	4509	File numbe r of where to find t he Extende d Action.
	4510
	4511	The “X” ar ray.
	4512	The “X” ar ray.
	4513	XUHUIX=XUU SER,ONE
	4514	XUHUIX(1)= XUUSER,ONE
	4515	XUHUIX(2)=
	4516	XUHUIX(3)= 2491224
	4517	XUHUIX(4)= 000558888
	4518
	4519	The “X1” a rray.
	4520	The “X1” a rray.
	4521	XUHUIX1=XU USER,ONE
	4522	XUHUIX1(1) =XUUSER,ON E
	4523	XUHUIX1(2) =
	4524	XUHUIX1(3) =2500704
	4525	XUHUIX1(4) =000220000
	4526
	4527	The “X2” a rray.
	4528	The “X2” a rray.
	4529	XUHUIX2=XU USER,ONE
	4530	XUHUIX2(1) =XUUSER,ON E
	4531	XUHUIX2(2) =
	4532	XUHUIX2(3) =2491224
	4533	XUHUIX2(4) =000558888
	4534	XUHUIXR=AX UHUI
	4535
	4536	Name of cr oss-refere nce being executed b y DIK.
	4537	Name of cr oss-refere nce being executed b y DIK.
	4538
	4539
	4540
	4541	File Acces s Security : Develope r Tools
	4542	Overview
	4543	The File A ccess Secu rity syste m is an op tional Ker nel module . It provi des an enh anced secu rity mecha nism for c ontrolling user acce ss to VA F ileMan fil es.
	4544	REF: For a n overview of the fu nctionalit y provided by the Fi le Access Security s ystem, see the “File Access Se curity” se ction in t he Kernel Systems Ma nagement G uide.
	4545	Field Leve l Protecti on
	4546	As before, the DUZ(0 ) check is not perfo rmed when a user tra verses fie lds in a D R string o r in a tem plate; fie ld-level p rotection is checked during th e template -building process, b ut not sub sequently when the t emplate is invoked b y a user. If you wan t to make the presen tation of fields con ditional, based on a user’s DU Z(0), bran ching logi c may be u sed as des cribed in the VA Fil eMan Progr ammers Man ual.
	4547	File Navig ation
	4548	Edit-type options th at navigat e to a sec ond file d o so by ca lling VA F ileMan and , hence, d epending o n the type of naviga tion and t he existin g file pro tection, r equires th at the use r have WRI TE access to change data in th e pointed- to file, D ELETE acce ss to dele te an entr y, and per haps LAYGO access to add a new entry.
	4549	Adding new entries w hen naviga ting to a file is co ntrolled b y LAYGO ac cess. If a pointing field allo ws LAYGO, as specifi ed in the data dicti onary, and the point ed-to file also allo ws LAYGO, the user d oes not ne ed explici t file acc ess to add entries. If the poi nted-to fi le is prot ected, how ever, the user needs explicit LAYGO acce ss to the file. DELE TE access is checked at the mo ment the u ser tries to delete a file ent ry.
	4550	When codin g calls, i f DIC(0) c ontains “L ”, DIC all ows the us er to add a new entr y if one o f three co nditions i s met:
	4551	The user h as been gr anted LAYG O access t o the file .
	4552	The user’s DUZ(0) is equal to “@”.
	4553	The DLAYGO variable is defined equal to the file n umber.
	4554	Use of DLA YGO When N avigating to Files
	4555	Use of inp ut templat es or ^DIE calls as part of ed it-type op tions perm its user a ccess to t he first f ile. Howev er, if nav igation to a second file is in volved, LA YGO is not automatic ally grant ed. One of the three condition s mentione d above mu st be met to allow n avigation to the sec ond file:
	4556	LAYGO acce ss is gran ted.
	4557	DUZ(0)=@.
	4558	DLAYGO var iable is s et.
	4559	Providing LAYGO acce ss by usin g the DLAY GO variabl e obviates the need for system administr ators to g rant LAYGO file acce ss to the pointed-to file via the File A ccess syst em. An exa mple of se tting DLAY GO in a te mplate is shown belo w:
	4560	Figure 35: File Acce ss Securit y—Setting DLAYGO in a template
	4561
	4562	A file poi nted-to by the Line Item file.
	4563	A file poi nted-to by the Line Item file.
	4564	INPUT TO W HAT FILE: RENTAL
	4565	EDIT WHICH FIELD: TR ANSACTION NUMBER
	4566	THEN EDIT FIELD: DAT E RENTED
	4567	THEN EDIT FIELD: S D LAYGO=8002 65
	4568
	4569	Set DLAYGO to the nu mber of th e file to be navigat ed-to via backward p ointing.
	4570	Set DLAYGO to the nu mber of th e file to be navigat ed-to via backward p ointing.
	4571	THEN EDIT FIELD: LIN E ITEM:
	4572	By ‘LIN E ITEM’, d o you mean the LINE ITEM File,
	4573	poi nting via its ‘RENTA L TRANSACT ION’ Field ? YES// Y <Enter> (Y ES)
	4574	WILL TERMI NAL USER B E ALLOWED TO SELECT PROPER ENT RY IN ‘LIN E ITEM’ FI LE? YES// <Enter> (Y ES)
	4575	DO YOU WAN T TO PERMI T ADDING A NEW ‘LINE ITEM’ ENT RY? NO// Y <Enter> ( YES)
	4576	WELL THEN, DO YOU WA NT TO FO RCE ADDI NG A NEW E NTRY EVERY TIME? NO/ / <Enter> (NO)
	4577	DO YOU WAN T AN ‘ADDI NG A NEW L INE ITEM’ MESSAGE? N O// N <Ent er> (NO)
	4578	EDIT WH ICH LINE I TEM FIELD: LINE ITEM
	4579	THEN ED IT LINE IT EM FIELD: RENTAL TRA NSACTION
	4580	THEN ED IT LINE IT EM FIELD: K DLAYGO
	4581
	4582	KILL DLAYG O upon exi t.
	4583	KILL DLAYG O upon exi t.
	4584	THEN ED IT LINE IT EM FIELD:
	4585
	4586	Use of DLA YGO in ^DI C Calls
	4587	When a use r attempts to add an entry at the top le vel of a f ile in a ^ DIC call, their file access se curity is checked fo r LAYGO ac cess to th e file. De velopers c an overrid e this che ck (and sa ve the sit e from hav ing to gra nt explici t LAYGO ac cess) by s etting DLA YGO to the file numb er in ques tion.
	4588	REF: For m ore inform ation on D LAYGO as u sed in ^DI C calls, s ee the VA FileMan De veloper’s Guide.
	4589	Use of DID EL in ^DIE Calls
	4590	When a use r attempts to delete an entry at the top level of a file in a ^DIE cal l, their f ile access security is checked for DELET E access t o the file . Develope rs can ove rride this check (an d save the site from having to grant exp licit DELE TE access) by settin g DIDEL to the file number in question. Use of DID EL does no t override a file’s “DEL” node s, however .
	4591	REF: For m ore inform ation on D IDEL as us ed in ^DIE calls, se e the VA F ileMan Dev eloper’s G uide.
	4592
	4593
	4594	Help Proce ssor: Deve loper Tool s
	4595	Entry and Exit Execu te Stateme nts
	4596	The HELP F RAME file (#9.2) con tains two fields for the entry of M code . Code in the Entry Execute St atement is executed just befor e the help frame is displayed. Code in t he Exit Ex ecute Stat ement is e xecuted af terwards.
	4597	Applicatio n Programm ing Interf ace (API)
	4598	Several AP Is are ava ilable for developer s to work with help processing . These AP Is are des cribed bel ow.
	4599	EN^XQH: Di splay Help Frames
	4600	Reference Type:Suppo rted
	4601	Category:H elp Proces sor
	4602	ICR #:1007 4
	4603	Descriptio n:This API displays a help fra me. It imm ediately c lears the screen and displays the help f rame (unli ke the EN1 ^XQH: Disp lay Help F rames API, which doe s not clea r the scre en and off ers the us er a choic e of wheth er to load the help frame).
	4604	Format:EN^ XQH
	4605	Make sure to perform the follo wing steps before ca lling this API:
	4606	NEW all no n-namespac ed variabl es.
	4607	Set all in put variab les.
	4608	Call the A PI.
	4609	Input Vari ables:XQH: (required) Help Fram e name (th e .01 valu e from the HELP FRAM E file [#9 .2]).
	4610	Output:non e.
	4611	EN1^XQH: D isplay Hel p Frames
	4612	Reference Type:Suppo rted
	4613	Category:H elp Proces sor
	4614	ICR #:1007 4
	4615	Descriptio n:This API displays a help fra me as ACTI ON^XQH4(): Print Hel p Frame Tr ee does, e xcept that it does n ot clear t he screen beforehand , and prio r to loadi ng the hel p frame, E N1^XQH inv okes end o f page han dling (i.e ., prompti ng the use r “Enter r eturn to c ontinue or ‘^’ to qu it”). If t he user en ters an “^ ”, the hel p frame is not displ ayed. If t hey press <Enter>, t he help fr ame is dis played.
	4616	Format:EN1 ^XQH
	4617	Make sure to perform the follo wing steps before ca lling this API:
	4618	NEW all no n-namespac ed variabl es.
	4619	Set all in put variab les.
	4620	Call the A PI.
	4621	Input Vari able:XQH:( required) Help Frame name (the .01 value from the HELP FRAME file [#9. 2]).
	4622	Output:non e.
	4623	ACTION^XQH 4(): Print Help Fram e Tree
	4624	Reference Type:Suppo rted
	4625	Category:H elp Proces sor
	4626	ICR #:1008 0
	4627	Descriptio n:This API prints ou t all the help frame s in a hel p frame tr ee, includ ing a tabl e of conte nts showin g the rela tionships between he lp frames and the pa ge of the printout w here each help frame is found. Since hel p frames c an be refe renced by more than one help f rame, any help frame reference d multiple times app ears in th e table of contents in each ap propriate location, but the he lp text it self is pr inted only once. You can alter the forma t of the o utput with the xqfmt input par ameter.
	4628	Format:ACT ION^XQH4(x qhfy[,xqfm t])
	4629	Input Para meters:xqh fy:(requir ed) Help f rame name, equal to the .01 fi eld of the desired e ntry in th e HELP FRA ME file (# 9.2). Shou ld be set to the NAM E of the t op-level h elp frame for which a listing is desired .
	4630	xqfmt:(opt ional) Spe cifies the output fo rmat. Valu e of xqfmt can be:
	4631	T—Text of help frame s only (de fault).
	4632	R—Text of help frame s, plus a table of r elated fra mes and ke ywords (if any) for each help frame.
	4633	C—Complete listing ( text of he lp frames, table of related fr ames for e ach help f rame, and internal h elp frame names).
	4634	Output:non e.
	4635
	4636
	4637	Host Files : Develope r Tools
	4638	Applicatio n Programm ing Interf ace (API)
	4639	Several AP Is are ava ilable for developer s to work with Host files. The se APIs ar e describe d below.
	4640	The tradit ional meth od of work ing with H ost File S ystem (HFS ) files pr ior to Ker nel 8.0 wa s to use t he Device Handler AP I (^%ZIS). Using sev eral input parameter s, you cou ld open a Host file (given a H ost file d evice entr y in the D EVICE file [#3.5]). For exampl e:
	4641	Figure 36: Host File s—Opening a Host fil e using th e ^%ZIS AP I
	4642	S %ZIS(“HF SNAME”)=“A RCHIVE.DAT ”
	4643	S %ZIS(“HF SMODE”)=“W ”
	4644	S IOP=“HFS ” D ^%ZIS Q:POP
	4645	U IO D...
	4646
	4647	Kernel 8.0 provides a set of A PIs for wo rking with Host file s. The Hos t file API s are:
	4648	CLOSE^%ZIS HClose Hos t file ope ned by OPE N^%ZISH.
	4649	$$DEL^%ZIS HDelete Ho st file.
	4650	$$FTG^%ZIS HCopy line s from a H ost file i nto a glob al.
	4651	$$GATF^%ZI SHpend rec ords from a global t o a Host f ile.
	4652	$$GTF^%ZIS HCopy reco rds from a global in to a Host file.
	4653	$$LIST^%ZI SHGet a li st of file s in a dir ectory.
	4654	$$MV^%ZISH Rename Hos t file.
	4655	OPEN^%ZISH Open Host file (bypa ss Device Handler).
	4656	$$PWD^%ZIS HGet name of current directory .
	4657	$$STATUS^% ZISHReturn end-of-fi le status.
	4658	Table 3 li sts defini tions that apply for the Host file APIs:
	4659	Table 3: H ost file A PIs—Defini tions
	4660	Term
	4661	Definition
	4662	Path:
	4663	Full path specificat ion up to, but not i ncluding, the filena me. This i ncludes an y trailing slashes o r brackets . If the o perating s ystem allo ws shortcu ts, you ca n use them . Examples of valid paths incl ude:
	4664	DOSc:\scra tch\
	4665	UNIX/home/ scratch/
	4666	VMSUSER$:[ SCRATCH]
	4667	To specify the curre nt directo ry, use a path of NU LL (“”).
	4668	Filename:
	4669	Filename o f the file only. Do not includ e device o r director y specific ations.
	4670	Access mod e:
	4671	Access mod e when ope ning files . It can b e one of t he followi ng codes:
	4672	R—READ; us e the file for READs only.
	4673	W—WRITE; u se the fil e for writ ing. If th e file exi sts, it is truncated to a leng th of zero (0) first . If the f ile does n ot exist, it is crea ted.
	4674	A—PEND; us e the file for writi ng but sta rt writing at the en d of the c urrent fil e. If the file does not exist, it is cre ated.
	4675	B—BINARY f ile.
	4676
	4677	CLOSE^%ZIS H(): Close Host File
	4678	Reference Type:Suppo rted
	4679	Category:H ost Files
	4680	ICR #:2320
	4681	Descriptio n:This API closes a Host file that was o pened with the OPEN^ %ZISH(): O pen Host F ile API.
	4682	Format:CLO SE^%ZISH(h andle)
	4683	Input Para meters:han dle:(requi red) Handl e used whe n file was opened wi th the OPE N^%ZISH(): Open Host File API.
	4684	Output:non e.
	4685
	4686	Example
	4687	Figure 37: CLOSE^%ZI SH API—Exa mple
	4688	D OPEN^%ZI SH(“OUTFIL E”,“USER$: [ANONYMOUS ]”,“ARCHIV E.DAT”,“W” )
	4689	Q:POP
	4690	U IO F I=1 :1:100 W I ,“: ”,ARRA Y(I),!
	4691	D CLOSE^%Z ISH(“OUTFI LE”)
	4692
	4693	$$DEFDIR^% ZISH(): Ge t Default Host File Directory
	4694	Reference Type:Suppo rted
	4695	Category:H ost Files
	4696	ICR #:2320
	4697	Descriptio n:This ext rinsic fun ction gets the defau lt Host fi le directo ry. It has two modes :
	4698	NULL/Missi ng Paramet er—If it i s called w ith a NULL /missing p arameter, it returns the “defa ult direct ory for HF S files” f rom the KE RNEL SYSTE M PARAMETE RS file (# 8989.3).
	4699	Directory Parameter— If it is c alled with a paramet er, it mus t be the d irectory f or a file. This para meter is c hecked to see that i t is in th e correct format for the opera ting syste m in quest ion.
	4700	Format:$$D EFDIR^%ZIS H([df])
	4701	Make sure to perform the follo wing steps before ca lling this API:
	4702	NEW all no n-namespac ed variabl es.
	4703	Set all in put variab les.
	4704	Call the A PI.
	4705	Input Para meters:df: (optional) This is t he directo ry path up on which a simple fo rmat check is made. For the NT operating system it changes “ /” to “\” and makes sure that there is a trailing “\”. There is no err or respons e.
	4706	Output:ret urns:Retur ns the def ault Host file direc tory.
	4707
	4708	$$DEL^%ZIS H(): Delet e Host Fil e
	4709	Reference Type:Suppo rted
	4710	Category:H ost Files
	4711	ICR #:2320
	4712	Descriptio n:This ext rinsic fun ction dele tes Host f iles. You can delete one or ma ny Host fi les, depen ding on ho w you set up the arr ay whose n ame you pa ss as the second inp ut paramet er.
	4713	Format:$$D EL^%ZISH(p ath,arrnam e)
	4714	Input Para meters:pat h:(require d) Full pa th, up to but not in cluding th e filename .
	4715	arrname:(r equired) F ully resol ved array name conta ining the files to d elete as s ubscripts at the nex t descende nt subscri pt level. For exampl e, to dele te two fil es, FILE1. DAT and FI LE2.DAT, s et up the array as:
	4716	ARRAY(“FIL E1.DAT”)=“ ”
	4717	ARRAY(“FIL E2.DAT”)=“ ”
	4718	Pass the a rray name “ARRAY” as the arrna me paramet er. Wildca rd specifi cations ca nnot be us ed with th is functio n.
	4719	Output:ret urns:Retur ns:
	4720	1—Success for all de letions.
	4721	0—Failure on at leas t one dele tion.
	4722
	4723	Example
	4724	>K FILESPE C
	4725	>S FILESPE C(“TMP.DAT ”)=“”
	4726	>S Y=$$DEL ^%ZISH(“\M YDIR\”,$NA (FILESPEC) )
	4727
	4728	$$FTG^%ZIS H(): Load Host File into Globa l
	4729	Reference Type:Suppo rted
	4730	Category:H ost Files
	4731	ICR #:2320
	4732	Descriptio n:This ext rinsic fun ction load s a Host f ile into a global. E ach line o f the Host file beco mes the va lue of one node in t he global. You do no t need to open the H ost file b efore maki ng this ca ll; it is opened and closed by $$FTG^%ZI SH.
	4733	If a line from a Hos t file exc eeds 255 c haracters in length, the overf lows are s tored in o verflow no des for th at line, a s follows:
	4734	Figure 38: Host File s—Overflow lines in a Host fil e sample
	4735
	4736
	4737	Format:$$F TG^%ZISH(p ath,filena me,global_ ref,inc_su bscr[,ovfs ub])
	4738	Input Para meters:pat h:(require d) Full pa th, up to but not in cluding th e filename .
	4739	filename:( required) Name of th e file to open.
	4740	global_ref :(required ) Global r eference t o WRITE Ho st file to , in fully resolved (closed ro ot) format . This fun ction does not KILL the global before wr iting to i t.
	4741	At least o ne subscri pt must be numeric. This is th e incremen ting subsc ript (i.e. , the subs cript that $$FTG^%ZI SH increme nts to sto re each ne w global n ode). This subscript need not be the fin al subscri pt. For ex ample, to load into a WORD PRO CESSING fi eld, the i ncrementin g node is the second -to-last s ubscript; the final subscript is always zero.
	4742	inc_subscr :(required ) Identifi es the inc rementing subscript level. For example, if you pas s ^TMP(115 ,1,1,0) as the globa l_ref para meter and pass 3 as the inc_su bscr param eter, $$FT G^%ZISH in crements t he third s ubscript, such as ^T MP(115,1,x ), but WRI TEs nodes at the ful l global r eference, such as ^T MP(115,1,x ,0).
	4743	ovfsub:(op tional) Na me of subs cript leve l at which overflow nodes for lines (if any) shoul d be store d. Overflo ws occur i f a line i s greater than 255 c haracters. Further o verflows o ccur for e very addit ional 255 characters . The defa ult subscr ipt name a t which ov erflows ar e stored f or a line is “OVF”.
	4744	Output:ret urns:Retur ns:
	4745	1—Success.
	4746	0—Failure.
	4747
	4748	Example
	4749	>S Y=$$FTG ^%ZISH(“US ER$:[COMMO N]”,“MYFIL E.DAT”,$NA (^MYGLOBAL (612,1,0)) ,2)
	4750
	4751	$$GATF^%ZI SH(): Copy Global to Host File
	4752	Reference Type:Suppo rted
	4753	Category:H ost Files
	4754	ICR #:2320
	4755	Descriptio n:This ext rinsic fun ction is u sed in the same way as the $$G TF^%ZISH() : Copy Glo bal to Hos t File API . The one difference is that i f the file already e xists, $$G ATF^%ZISH appends gl obal nodes to the ex isting fil e rather t han trunca ting the e xisting fi le first.
	4756	REF: For m ore inform ation, see the $$GTF ^%ZISH(): Copy Globa l to Host File API d escription .
	4757	Format:$$G ATF^%ZISH( global_ref ,inc_subsc r,path,fil ename)
	4758	Input Para meters:glo bal_ref:(r equired) G lobal to R EAD lines from, full y resolved in closed root form .
	4759	inc_subscr :(required ) Identifi es the inc rementing subscript level. For example, if you pas s ^TMP(115 ,1,1,0) as the globa l_ref para meter, and pass 3 as the inc_s ubscr para meter, $$G ATF increm ents the t hird subsc ript (e.g. , ^TMP[115 ,1,x]), bu t READs no des at the full glob al referen ce (e.g., ^TMP[115,1 ,x,0]).
	4760	path: (req uired) Ful l path, up to but no t includin g the file name.
	4761	filename:( required) Name of th e file to open.
	4762	Output:ret urns:Retur ns:
	4763	1—Success.
	4764	0—Failure.
	4765
	4766	$$GTF^%ZIS H(): Copy Global to Host File
	4767	Reference Type:Suppo rted
	4768	Category:H ost Files
	4769	ICR #:2320
	4770	Descriptio n:This ext rinsic fun ction WRIT Es the val ues of nod es in a gl obal (at t he subscri pt level y ou specify ) to a Hos t file. If the Host file alrea dy exists, it is tru ncated to length zer o (0) befo re the cop y. You do not need t o open the Host file before ma king this call. The Host file is opened (in WRITE mode) and closed by $$GTF^%ZIS H.
	4771	Format:$$G TF^%ZISH(g lobal_ref, inc_subscr ,path,file name)
	4772	Input Para meters:glo bal_ref:(r equired) G lobal to R EAD lines from, full y resolved in closed root form .
	4773	inc_subscr :(required ) Identifi es the inc rementing subscript level. For example, if you pas s ^TMP(115 ,1,1,0) as the globa l_ref para meter, and pass 3 as the inc_s ubscr para meter, $$G TF increme nts the th ird subscr ipt (e.g., ^TMP[115, 1,x]), but READs nod es at the full globa l referenc e (e.g., ^ TMP[115,1, x,0]).
	4774	path:(requ ired) Full path, up to but not including the filen ame.
	4775	filename:( required) Name of th e file to open.
	4776	Output:ret urns:Retur ns:
	4777	1—Success.
	4778	0—Failure.
	4779
	4780	Example
	4781	>S Y=$$GTF ^%ZISH($NA (^MYGLOBAL (612,1,0)) ,2,“USER$: [COMMON]”, “MYFILE.DA T”)
	4782
	4783	$$LIST^%ZI SH(): List Directory
	4784	Reference Type:Suppo rted
	4785	Category:H ost Files
	4786	ICR #:2320
	4787	Descriptio n:This ext rinsic fun ction retu rns a list of file n ames in th e current directory. The list is returne d in an ar ray in the variable named by t he third p arameter.
	4788	Format:$$L IST^%ZISH( path,arrna me,retarrn am)
	4789	Input Para meters:pat h:(require d) Full pa th, up to but not in cluding an y filename . For curr ent direct ory, pass the NULL s tring.
	4790	arrname:(r equired) F ully resol ved array name conta ining file specifica tions to l ist at the next desc endent sub script lev el.
	4791	For exampl e, to list all files , set one node in th e named ar ray, at su bscript “* ”, equal t o NULL. To list all files begi nning with “E” and “ L”, using the ARRAY array, set the nodes :
	4792	ARRAY(“E*” )=“”
	4793	ARRAY(“L*” )=“”
	4794	Pass the n ame “ARRAY ” as the a rrname par ameter. Yo u can use the asteri sk wildcar d in the f ile specif ication.
	4795	retarrnam: (required) Fully res olved arra y name to return the list of m atching fi lenames. Y ou should ordinarily KILL this array fir st (it is not purged by LIST^% ZISH).
	4796	Output Par ameters:re tarrnam:$$ LIST^%ZISH populates the array named in the third input para meter with all match ing files it finds i n the dire ctory you specify. I t populate s the arra y in the f ormat:
	4797	ARRAY(“fil ename1”)=“ ”
	4798	ARRAY(“fil ename2”)=“ ”
	4799	(etc.)
	4800	Output:ret urns:Retur ns:
	4801	1—Success.
	4802	0—Failure.
	4803
	4804	Example
	4805	>K FILESPE C,FILE
	4806	>S FILESPE C(“L”)=“” ,FILESPEC( “P”)=“”
	4807	>S Y=$$LIS T^%ZISH(“” ,“FILESPEC ”,“FILE”)
	4808
	4809	$$MV^%ZISH (): Rename Host File
	4810	Reference Type:Suppo rted
	4811	Category:H ost Files
	4812	ICR #:2320
	4813	Descriptio n:This ext rinsic fun ction rena mes a Host file. The function performs t he renamin g, regardl ess of the underlyin g operatin g system, by first c opying the file to t he new nam e/location and then deleting t he origina l file at the old na me/locatio n.
	4814	Format:$$M V^%ZISH([p ath1,]file name1[,pat h2],filena me2)
	4815	Input Para meters:pat h1:(option al) Full p ath of the original file, up t o but not including the filena me. If nul l, it defa ults to $$ DEFDIR^%ZO SV.
	4816	filename1: (required) Name of t he origina l file.
	4817	path2:(opt ional) Ful l path of renamed fi le, up to but not in cluding th e filename . If null, it defaul ts to $$DE FDIR^%ZOSV .
	4818	filename2: (required) Name of t he renamed file.
	4819	Output:ret urns:Retur ns:
	4820	1—Success.
	4821	0—Failure.
	4822
	4823	Example
	4824	>S Y=$$MV^ %ZISH(“”,“ TMP.DAT”,“ ”,“ZXG”_I_ “.DAT”)
	4825
	4826	OPEN^%ZISH (): Open H ost File
	4827	Reference Type:Suppo rted
	4828	Category:H ost Files
	4829	ICR #:2320
	4830	Descriptio n:This API opens a H ost file w ithout usi ng the Dev ice Handle r. You can USE the d evice name returned in IO. You can then READ and W RITE from the opened Host file (dependin g on what access mod e you used to open t he file).
	4831	To close t he Host fi le, use th e CLOSE^%Z ISH API wi th the han dle you us ed to open the file.
	4832	Format:OPE N^%ZISH([h andle][,pa th,]filena me,mode[,m ax][,subty pe])
	4833	Input Para meters:han dle:(optio nal) Uniqu e name you supply to identify the opened device.
	4834	path:(opti onal) Full directory path, up to but not including the filen ame. If no t supplied , the defa ult HFS di rectory is used.
	4835	filename:( required) Name of th e file to open.
	4836	mode:(requ ired) Mode to open f ile:
	4837	W—WRITE.
	4838	R—READ.
	4839	A—PEND.
	4840	B—BLOCK (f ixed recor d size).
	4841	max:(optio nal) Maxim um record size for a new file.
	4842	subtype:(o ptional) F ile subtyp e.
	4843	Output Var iables:POP :A value o f zero (0) means the file was opened suc cessfully; a positiv e value me ans the fi le was not opened.
	4844	IO:Name of the opene d file in the format to use fo r M USE an d CLOSE co mmands.
	4845
	4846	Example
	4847	Figure 39: OPEN^%ZIS H API—Exam ple
	4848	D OPEN^%ZI SH(“FILE1” ,“USER$:[A NONYMOUS]” ,“ARCHIVE. DAT”,“A”)
	4849	Q:POP
	4850	U IO F I=1 :1:100 W I ,“: ”,ARRA Y(I),!
	4851	D CLOSE^%Z ISH(“FILE1 ”)
	4852
	4853	$$PWD^%ZIS H: Get Cur rent Direc tory
	4854	Reference Type:Suppo rted
	4855	Category:H ost Files
	4856	ICR #:2320
	4857	Descriptio n:This ext rinsic fun ction retu rns the na me of the current wo rking dire ctory.
	4858	Format:$$P WD^%ZISH
	4859	Input Para meters:non e.
	4860
	4861	Output:ret urns:Retur ns:
	4862	String—The string re presenting the curre nt directo ry specifi cation, in cluding de vice if an y.
	4863	NULL—If a problem oc curs while retrievin g the curr ent direct ory.
	4864
	4865	Example
	4866	>S Y=$$PWD ^%ZISH()
	4867
	4868	$$STATUS^% ZISH: Retu rn End-of- File Statu s
	4869	Reference Type:Suppo rted
	4870	Category:H ost Files
	4871	ICR #:2320
	4872	Descriptio n:This ext rinsic fun ction retu rns the cu rrent end- of-file st atus. If e nd-of-file has been reached, $ $STATUS^%Z ISH return s:
	4873	1—End-of-f ile (EOF) has been r eached.
	4874	0—End-of-f ile (EOF) has not be en reached .
	4875	Format:$$S TATUS^%ZIS H
	4876	Input Para meters:non e.
	4877	Output:ret urns:Retur ns:
	4878	1—End-of-f ile (EOF) has been r eached.
	4879	0—End-of-f ile (EOF) has not be en reached .
	4880
	4881	Example
	4882	Figure 40: $$STATUS^ %ZISH API— Example
	4883	D OPEN^%ZI SH(“INFILE ”,“USER$:[ ANONYMOUS] ”,“ZXG.DAT ”,“R”)
	4884	Q:POP
	4885	U IO F I=1 :1 R X:DTI ME Q:$$STA TUS^%ZISH S ^TMP($J ,“ZXG”,I)= X
	4886	D CLOSE^%Z ISH(“INFIL E”)
	4887
	4888

	4889	Institutio n File: De veloper To ols
	4890	Applicatio n Programm ing Interf ace (API)
	4891	Several AP Is are ava ilable for developer s to work with the I NSTITUTION file (#4) . These AP Is are des cribed bel ow.
	4892	$$ACTIVE^X UAF4(): In stitution Active Fac ility (Tru e/False)
	4893	Reference Type:Suppo rted
	4894	Category:I nstitution File
	4895	ICR #:2171
	4896	Descriptio n:This ext rinsic fun ction, giv en the Int ernal Entr y Number ( IEN) in th e INSTITUT ION file ( #4), retur ns the Boo lean value for the q uestion—is this an a ctive faci lity? It c hecks to s ee if the INACTIVE F ACILITY FL AG field ( #101) is n ot set.
	4897	Format:$$A CTIVE^XUAF 4(ien)
	4898	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	4899	Output:ret urns:Retur ns a Boole an value:
	4900	True (non- zero)—Stat ion Number is an act ive facili ty.
	4901	False (zer o)—Station Number is not an ac tive facil ity. The I NACTIVE FA CILITY FLA G field (# 101) has a value ind icating it is inacti ve.
	4902
	4903	CDSYS^XUAF 4(): Codin g System N ame
	4904	Reference Type:Suppo rted
	4905	Category:I nstitution File
	4906	ICR #:2171
	4907	Descriptio n:This API returns t he Coding System nam e.
	4908	Format:CDS YS^XUAF4(y )
	4909	Input Para meters:y:( required) Pass by re ference, r eturns:
	4910	Y(coding_s ystem) =$D _of_local_ system^ co ding_syste m name
	4911	Output Par ameters:y: Passed by reference, returns:
	4912	Y(coding_s ystem) =$D _of_local_ system^ co ding_syste m name
	4913
	4914	CHILDREN^X UAF4(): Li st of Chil d Institut ions for a Parent
	4915	Reference Type:Suppo rted
	4916	Category:I nstitution File
	4917	ICR #:2171
	4918	Descriptio n:This API returns a list of a ll institu tions that make up a given Vet erans Inte grated Ser vice Netwo rk (VISN), parent in stitution entered in the “pare nt” input parameter.
	4919	Format:CHI LDREN^XUAF 4(array,pa rent)
	4920	Input Para meters:arr ay:(requir ed) $NAME reference to store t he list of instituti ons that m ake up the parent VI SN institu tion for t he “parent ” input pa rameter.
	4921	parent:(re quired) Pa rent (VISN ) institut ion lookup value, an y of the f ollowing:
	4922	Internal E ntry Numbe r (IEN); h as the ` i n front of it.
	4923	Station Nu mber.
	4924	Station Na me.
	4925	Output:ret urns:Retur ns the arr ay populat ed with th e list of institutio ns that ma ke up the parent VIS N.
	4926	Variable a rray (“c”, ien)=stati on_name^st ation_numb er
	4927
	4928	$$CIRN^XUA F4(): Inst itution CI RN-enabled Field Val ue
	4929	Reference Type:Suppo rted
	4930	Category:I nstitution File
	4931	ICR #:2171
	4932	Descriptio n:This ext rinsic fun ction retu rns the va lue of the CIRN-enab led field from the I NSTITUTION file (#4) .
	4933	Format:$$C IRN^XUAF4( inst[,valu e])
	4934	Input Para meters:ins t:(require d) Institu tion looku p value, a ny of the following:
	4935	Internal E ntry Numbe r (IEN); h as the ` i n front of it.
	4936	Station Nu mber.
	4937	Station Na me.
	4938	value:(opt ional) Res tricted to use by CI RN. This i nput param eter allow s the sett ing of the field to a new valu e.
	4939	Output:ret urns:Retur ns the CIR N-enabled field valu e.
	4940
	4941	F4^XUAF4() : Institut ion Data f or a Stati on Number
	4942	Reference Type:Suppo rted
	4943	Category:I nstitution File
	4944	ICR #:2171
	4945	Descriptio n:This API returns t he Interna l Entry Nu mber (IEN) and other instituti on data, i ncluding h istorical informatio n, for a g iven STATI ON NUMBER (#99) in t he INSTITU TION file (#4).
	4946	Format:F4^ XUAF4(sta, [.]array[, flag][,dat e])
	4947	Input Para meters:sta :(required ) Station Number.
	4948	[.]array:( required) $NAME refe rence for return val ues.
	4949	flag:(opti onal) Flag s that rep resent the Station N umber Stat us. Possib le values are:
	4950	A—Active e ntries onl y.
	4951	M—Medical treating f acilities only.
	4952	date:(opti onal) Retu rn name on this VA F ileMan int ernal date .
	4953	Output:arr ay:IEN or “0^error m essage”.
	4954	array(“NAM E”):Name.
	4955	array(“VA NAME”):Off icial VA N ame.
	4956	array(“STA TION NUMBE R”):Statio n Number.
	4957	array(“TYP E”):Facili ty Type Na me.
	4958	array(“INA CTIVE”):In active Dat e (0=not i nactive).
	4959	NOTE: If i nactive da te not ava ilable, th en 1.
	4960	array(“REA LIGNED TO” ):IEN^stat ion number ^date.
	4961	array(“REA LIGNED FRO M”):IEN^st ation numb er^date.
	4962	array(“MER GE”,IEN”): Merged Rec ords.
	4963
	4964	Example
	4965	Figure 41: F4^XUAF4 API—Exampl e
	4966	>D F4^XUAF 4(“528A8”, .ARRAY)
	4967
	4968	>ZW ARRAY
	4969	ARRAY=7020
	4970	ARRAY(“INA CTIVE”)=0
	4971	ARRAY(“NAM E”)=ALBANY
	4972	ARRAY(“REA LIGNED FRO M”)=500^50 0^3000701
	4973	ARRAY(“STA TION NUMBE R”)=528A8
	4974	ARRAY(“TYP E”)=VAMC
	4975	ARRAY(“VA NAME”)=VA HEALTHCARE NETWORK U PSTATE NEW YORK SYST EM VISN 2 - ALBANY D IVISION
	4976
	4977	$$ID^XUAF4 (): Instit ution Iden tifier
	4978	Reference Type:Suppo rted
	4979	Category:I nstitution File
	4980	ICR #:2171
	4981	Descriptio n:This ext rinsic fun ction retu rns the Id entifier ( ID) of an INSTITUTIO N file (#4 ) entry fo r a given Coding Sys tem and In ternal Ent ry Number (IEN).
	4982	Format:$$I D^XUAF4(cd sys,ien)
	4983	Input Para meters:cds ys:(requir ed) CDSYS is an exis ting codin g system o f the INST ITUTION fi le (#4). T o see the existing c oding syst em in the file:
	4984	>D CDSYS^X UAF4(.Y)
	4985	ien:(requi red) Inter nal Entry Number (IE N) of the institutio n in quest ion.
	4986	Output:ret urns:Retur ns the INS TITUTION f ile (#4) I dentifier (ID) assoc iated with the given Coding Sy stem and I EN.
	4987
	4988	$$IDX^XUAF 4(): Insti tution IEN (Using Co ding Syste m & ID)
	4989	Reference Type:Suppo rted
	4990	Category:I nstitution File
	4991	ICR #:2171
	4992	Descriptio n:This ext rinsic fun ction retu rns the In ternal Ent ry Number (IEN) of a n INSTITUT ION file ( #4) entry for a give n Coding S ystem and Identifier (ID) pair .
	4993	Format:$$I DX^XUAF4(c dsys,id)
	4994	Input Para meters:cds ys:(requir ed) CDSYS is an exis ting codin g system o f the INST ITUTION fi le (#4). T o see the existing c oding syst em in the file:
	4995	>D CDSYS^X UAF4(.Y)
	4996	id:(requir ed) ID is the identi fier assoc iated with the codin g system. The statio n number, for exampl e, is the identifier for the V ASTANUM co ding syste m and NPI number is the ID for the NPI c oding syst em.
	4997	Output:ret urns:Retur ns the INS TITUTION f ile (#4) I nternal En try Number (IEN) ass ociated wi th the giv en Coding System and Identifie r (ID).
	4998
	4999	$$IEN^XUAF 4(): IEN f or Station Number
	5000	Reference Type:Suppo rted
	5001	Category:I nstitution File
	5002	ICR #:2171
	5003	Descriptio n:This ext rinsic fun ction retu rns the In ternal Ent ry Number (IEN) of t he entry f or a given STATION N UMBER fiel d (#99) in the INSTI TUTION fil e (#4).
	5004	Format:$$I EN^XUAF4(s ta)
	5005	Input Para meters:sta :(required ) Station Number.
	5006	Output:ret urns:Retur ns:
	5007	IEN—Intern al Entry N umber.
	5008	NULL—Error .
	5009
	5010	Example
	5011	>S X=$$IEN ^XUAF4(“52 8A5”)
	5012
	5013	>W X
	5014	532
	5015
	5016	$$LEGACY^X UAF4(): In stitution Realigned/ Legacy (Tr ue/False)
	5017	Reference Type:Suppo rted
	5018	Category:I nstitution File
	5019	ICR #:2171
	5020	Descriptio n:This ext rinsic fun ction, giv en the STA TION NUMBE R field (# 99) in the INSTITUTI ON file (# 4), return s the Bool ean value for the qu estion—has this stat ion number been real igned? Is it a legac y Station Number?
	5021	Format:$$L EGACY^XUAF 4(sta)
	5022	Input Para meters:sta :(required ) The STAT ION NUMBER field (#9 9) value i n the INST ITUTION fi le (#4) fo r the Stat ion Number in questi on
	5023	Output:ret urns:Retur ns a Boole an value:
	5024	True (non- zero)—Stat ion Number has been realigned; it is a l egacy Stat ion Number .
	5025	False (zer o)—Station Number ha s not been realigned ; it is no t a legacy Station N umber.
	5026
	5027	$$LKUP^XUA F4(): Inst itution Lo okup
	5028	Reference Type:Suppo rted
	5029	Category:I nstitution File
	5030	ICR #:2171
	5031	Descriptio n:This ext rinsic fun ction retu rns the IE N or zero when doing a lookup on the INS TITUTION f ile (#4).
	5032	Format:$$L KUP^XUAF4( inst)
	5033	Input Para meters:ins t:(require d) Institu tion looku p value, a ny of the following:
	5034	Internal E ntry Numbe r (IEN); h as the ` i n front of it.
	5035	Station Nu mber.
	5036	Station Na me.
	5037	Output:ret urns:Retur ns:
	5038	IEN—Intern al Entry N umber.
	5039	Zero (0).
	5040
	5041	LOOKUP^XUA F4(): Look Up Instit ution Iden tifier
	5042	Reference Type:Suppo rted
	5043	Category:I nstitution File
	5044	ICR #:2171
	5045	Descriptio n:This API lookup ut ility allo ws a user to select an Institu tion by Co ding Syste m and ID. It prompts a user fo r a Coding System an d then pro mpts for a n Identifi er—it’s an IX^DIC AP I call on a New Styl e cross-re ference of the ID fi eld (#.02) of the ID ENTIFIER f ield (#999 9) multipl e in the I NSTITUTION file (#4) .
	5046	Format:LOO KUP^XUAF4( )
	5047	Input Para meters:See IX^DICFor input inf ormation, see the IX ^DIC docum entation i n the VA F ileMan Dev eloper’s G uide.
	5048	Output:See IX^DICFor output in formation, see the I X^DIC docu mentation in the VA FileMan De veloper’s Guide.
	5049
	5050	Example
	5051	Figure 42: LOOKUP^XU AF4 API—Ex ample
	5052	Select INSTITUTI ON CODING SYSTEM: DM IS
	5053	ID: 00 37
	5054	DMIS 0037 WALT ER REED DC U SAH 6 88CN
	5055
	5056	$$MADD^XUA F4(): Inst itution Ma iling Addr ess
	5057	Reference Type:Suppo rted
	5058	Category:I nstitution File
	5059	ICR #:2171
	5060	Descriptio n:This ext rinsic fun ction retu rns the ma iling addr ess inform ation for an institu tion in a caret-deli mited stri ng (i.e., streetaddr ^city^stat e^zip) for a given I nternal En try Number (IEN) in the INSTIT UTION file (#4).
	5061	Format:$$M ADD^XUAF4( ien)
	5062	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5063	Output:ret urns:Retur ns the ins titution m ailing add ress in a caret-deli mited stri ng:
	5064	streetaddr ^city^stat e^zip
	5065
	5066	$$NAME^XUA F4(): Inst itution Of ficial Nam e
	5067	Reference Type:Suppo rted
	5068	Category:I nstitution File
	5069	ICR #:2171
	5070	Descriptio n:This ext rinsic fun ction retu rns the OF FICIAL NAM E field (# 100) value in the IN STITUTION file (#4) for an ins titution g iven its I nternal En try Number (IEN). Ho wever, If Field #100 is null, the NAME f ield (#.01 ) in the I NSTITUTION file (#4) is return ed.
	5071	Format:$$N AME^XUAF4( ien)
	5072	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5073	Output:ret urns:Retur ns either of the fol lowing:
	5074	OFFICIAL N AME field (#100) val ue in the INSTITUTIO N file (#4 )—If Field #100 is n ot null.
	5075	NAME field (#.01) va lue in the INSTITUTI ON file (# 4)—If Fiel d #100 is null.
	5076
	5077	$$NNT^XUAF 4(): Insti tution Sta tion Name, Number, a nd Type
	5078	Reference Type:Suppo rted
	5079	Category:I nstitution File
	5080	ICR #:2171
	5081	Descriptio n:This ext rinsic fun ction retu rns the st ation info rmation fo r an insti tution in a caret-de limited st ring (i.e. , station_ name^stati on_number^ station_ty pe) for a given Inte rnal Entry Number (I EN) in the INSTITUTI ON file (# 4).
	5082	Format:$$N NT^XUAF4(i en)
	5083	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5084	Output:ret urns:Retur ns the ins titution s tation inf ormation i n a caret- delimited string:
	5085	station_na me^station _number^st ation_type
	5086
	5087	$$NS^XUAF4 (): Instit ution Name and Stati on Number
	5088	Reference Type:Suppo rted
	5089	Category:I nstitution File
	5090	ICR #:2171
	5091	Descriptio n:This ext rinsic fun ction retu rns the in stitution informatio n in a car et-delimit ed string (i.e., ins titution_n ame^statio n_number) for a give n Internal Entry Num ber (IEN) in the INS TITUTION f ile (#4).
	5092	Format:$$N S^XUAF4(ie n)
	5093	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5094	Output:ret urns:Retur ns the ins titution i nformation in a care t-delimite d string:
	5095	institutio n_name^sta tion_numbe r
	5096
	5097	$$O99^XUAF 4(): IEN o f Merged S tation Num ber
	5098	Reference Type:Suppo rted
	5099	Category:I nstitution File
	5100	ICR #:2171
	5101	Descriptio n:This ext rinsic fun ction retu rns the In ternal Ent ry Number (IEN) of t he valid S TATION NUM BER in the INSTITUTI ON file (# 4), if thi s entry wa s merged d uring the INSTITUTIO N file (#4 ) cleanup process (e .g., due t o a duplic ate STATIO N NUMBER f ield [#99] ). This fu nction may be used b y applicat ion develo pers to re -point the ir INSTITU TION file (#4) refer ences to a valid ent ry complet e with Sta tion Numbe r.
	5102	Format:$$O 99^XUAF4(i en)
	5103	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5104	Output:ret urns:Retur ns the Int ernal Entr y Number ( IEN) of th e INSTITUT ION file ( #4) entry with a val id STATION NUMBER fi led (#99)— the Statio n Number d eleted fro m the inpu t IEN duri ng the cle anup proce ss (i.e., Kernel pat ch XU8.0 206).
	5105
	5106	Example
	5107	>S NEWIEN= $$O99^XUAF 4(6538)
	5108
	5109	>W NEWIEN
	5110	6164
	5111	>W ^DIC(4, 6164,99)
	5112	519HB^^^
	5113
	5114	$$PADD^ XU AF4(): Ins titution P hysical Ad dress
	5115	Reference Type:Suppo rted
	5116	Category:I nstitution File
	5117	ICR #:2171
	5118	Descriptio n:This ext rinsic fun ction retu rns the ph ysical add ress infor mation for an instit ution in a caret-del imited str ing (stree taddr^city ^state^zip ) for a gi ven Intern al Entry N umber (IEN ) in the I NSTITUTION file (#4) .
	5119	Format:$$P ADD^XUAF4( ien)
	5120	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5121	Output:ret urns:Retur ns the ins titution p hysical ad dress in a caret-del imited str ing:
	5122	streetaddr ^city^stat e^zip
	5123
	5124	PARENT^XUA F4(): Pare nt Institu tion Looku p
	5125	Reference Type:Suppo rted
	5126	Category:I nstitution File
	5127	ICR #:2171
	5128	Descriptio n:This API returns a list of a ll institu tions that make up a given Vet erans Inte grated Ser vice Netwo rk (VISN), parent in stitution entered in the “look up” input parameter.
	5129	Format:PAR ENT^XUAF4( array,look up[,type])
	5130	Input Para meters:arr ay:(requir ed) $NAME reference to store t he list of the paren t (VISN) i nstitution for the “ lookup” in put parame ter instit ution.
	5131	lookup:(re quired) Pa rent (VISN ) institut ion lookup value, an y of the f ollowing:
	5132	Internal E ntry Numbe r (IEN); h as the ` i n front of it.
	5133	Station Nu mber.
	5134	Station Na me.
	5135	type:(opti onal) Type of instit ution from the INSTI TUTION ASS OCIATION T YPES file (#4.05, de fault is V ISN).
	5136	Output:ret urns:Retur ns the arr ay populat ed with th e list of parent (VI SN) instit utions.
	5137	Variable a rray (“P”, PIEN)=STAT ION_NAME^S TATION_NUM BER
	5138	NOTE: With the busin ess rule t hat instit utions can only have one paren t per type , if you s pecify the input par ameter typ e, you get an array that only has one PI EN in it. If the typ e paramete r is left blank, it finds all parents fo r the inst itution an d lists th en in the array.
	5139
	5140	$$PRNT^XUA F4(): Inst itution Pa rent Facil ity
	5141	Reference Type:Suppo rted
	5142	Category:I nstitution File
	5143	ICR #:2171
	5144	Descriptio n:This ext rinsic fun ction retu rns the pa rent facil ity instit ution info rmation in a caret-d elimited s tring (ien ^station_n umber^name ) for a gi ven child facility S TATION NUM BER field (#99) in t he INSTITU TION file (#4).
	5145	Format:$$P RNT^XUAF4( sta)
	5146	Input Para meters:sta :(required ) The STAT ION NUMBER field (#9 9) value i n the INST ITUTION fi le (#4) fo r the chil d facility whose par ent facili ty informa tion is be ing reques ted.
	5147	Output:ret urns:Retur ns the par ent facili ty institu tion infor mation in a caret-de limited st ring:
	5148	ien^statio n_number^n ame
	5149
	5150	$$RF^XUAF4 (): Realig ned From I nstitution Informati on
	5151	Reference Type:Suppo rted
	5152	Category:I nstitution File
	5153	ICR #:
	5154	Descriptio n:This ext rinsic fun ction retu rns the in formation that is po inted to i n the REAL IGNED FROM field (#. 06) in the HISTORY f ield (#999 ) multiple in a care t-delimite d string ( ien^statio n_number^e ffective_d ate) for a given Int ernal Entr y Number ( IEN) in th e INSTITUT ION file ( #4).
	5155	Format:$$R F^XUAF4(ie n)
	5156	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5157	Output:ret urns:Retur ns the rea ligned fro m institut ion inform ation in a caret-del imited str ing:
	5158	ien^statio n_number^e ffective_d ate
	5159
	5160	Example
	5161	>S IEN=$$R F^XUAF4(70 20)
	5162
	5163	>W IEN
	5164	500^500^30 00701
	5165
	5166	$$RT^XUAF4 (): Realig ned To Ins titution I nformation
	5167	Reference Type:Suppo rted
	5168	Category:I nstitution File
	5169	ICR #:
	5170	Descriptio n:This ext rinsic fun ction retu rns the in formation that is po inted to i n the REAL IGNED TO f ield (#.05 ) in the H ISTORY fie ld (#999) multiple i n a caret- delimited string (ie n^station_ number^eff ective_dat e) for a g iven Inter nal Entry Number (IE N) in the INSTITUTIO N file (#4 ).
	5171	Format:$$R T^XUAF4(ie n)
	5172	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5173	Output:ret urns:Retur ns the rea ligned to institutio n informat ion in a c aret-delim ited strin g:
	5174	ien^statio n_number^e ffective_d ate
	5175
	5176	Example
	5177	>S IEN=$$R T^XUAF4(50 0)
	5178
	5179	>W IEN
	5180	7020^528A8 ^3000701
	5181
	5182	SIBLING^XU AF4(): Sib ling Insti tution Loo kup
	5183	Reference Type:Suppo rted
	5184	Category:I nstitution File
	5185	ICR #:2171
	5186	Descriptio n:This API returns a list of a ll institu tions that make up a given Vet erans Inte grated Ser vice Netwo rk (VISN), parent in stitution entered in the “chil d” input p arameter.
	5187	Format:SIB LING^XUAF4 (array,chi ld[,type])
	5188	Input Para meters:arr ay:(requir ed) $NAME reference to store t he list of all insti tutions of a parent (VISN) ins titution f or the “ch ild” input parameter instituti on.
	5189	child:(req uired) Chi ld institu tion looku p value, a ny of the following:
	5190	Internal E ntry Numbe r (IEN); h as the ` i n front of it.
	5191	Station Nu mber.
	5192	Station Na me.
	5193	type:(opti onal) Type of instit ution from the INSTI TUTION ASS OCIATION T YPES file (#4.05, de fault is V ISN).
	5194	Output:ret urns:Retur ns the arr ay populat ed with th e list of all instit utions of the parent (VISN) in stitution.
	5195	Variable a rray(“P”,P IEN, “C”,C IEN)=STATI ON_NAME^ST ATION_NUMB ER
	5196	NOTE: With the busin ess rule t hat instit utions can only have one paren t per type , if you s pecify the input par ameter typ e, you get an array that only has one PI EN in it. If the typ e paramete r is left blank, it finds all parents fo r the inst itution an d lists th en in the array. Als o, the inp ut site (i .e., ”chil d” input p arameter) is include d in the l ist.
	5197	$$STA^XUAF 4(): Stati on Number for IEN
	5198	Reference Type:Suppo rted
	5199	Category:I nstitution File
	5200	ICR #:2171
	5201	Descriptio n:This ext rinsic fun ction retu rns the ST ATION NUMB ER field ( #99) for t he entry o f a given Internal E ntry Numbe r (IEN) in the INSTI TUTION fil e (#4).
	5202	Format:$$S TA^XUAF4(i en)
	5203	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5204	Output:ret urns:Retur ns the Sta tion Numbe r.
	5205
	5206	Example
	5207	>S STA=$$S TA^XUAF4(7 020)
	5208
	5209	>W STA
	5210	528A8
	5211
	5212	$$TF^XUAF4 (): Treati ng Facilit y (True/Fa lse)
	5213	Reference Type:Suppo rted
	5214	Category:I nstitution File
	5215	ICR #:2171
	5216	Descriptio n:This ext rinsic fun ction, giv en the Int ernal Entr y Number ( IEN) in th e INSTITUT ION file ( #4), retur ns the Boo lean value for the q uestion—is this a me dical trea ting facil ity?
	5217	Format:$$T F^XUAF4(ie n)
	5218	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question .
	5219	Output:ret urns:Retur ns a Boole an value:
	5220	True (non- zero)—Trea ting facil ity.
	5221	False (zer o)—Not a T reating fa cility.
	5222
	5223	Example
	5224	>S TF=$$TF ^XUAF4(702 0)
	5225
	5226	>W TF
	5227	1
	5228
	5229	$$WHAT^XUA F4(): Inst itution Si ngle Field Informati on
	5230	Reference Type:Suppo rted
	5231	Category:I nstitution File
	5232	ICR #:2171
	5233	Descriptio n:This ext rinsic fun ction retu rns the da ta from a single fie ld given t he Interna l Entry Nu mber (IEN) and the s pecific fi eld reques ted in the INSTITUTI ON file (# 4).
	5234	Format:$$W HAT^XUAF4( ien,field)
	5235	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the ins titution i n question (pointer value to t he INSTITU TION file (#4).
	5236	field:(req uired) fie ld number of the fie ld in ques tion.
	5237	Output:ret urns:Retur ns the val ue in the specified field.
	5238
	5239	$$IEN^XUMF (): Instit ution IEN (Using IFN , Coding S ystem, & I D)
	5240	Reference Type:Suppo rted
	5241	Category:I nstitution File
	5242	ICR #:3795
	5243	Descriptio n:This ext rinsic fun ction retu rns the In ternal Ent ry Number (IEN) for a given In ternal Fil e Number ( IFN), Codi ng System, and Ident ifier (ID) .
	5244	Format:$$I EN^XUMF(if n,cdsys,id )
	5245	Input Para meters:ifn :(required ) Internal File Numb er (IFN).
	5246	cdsys:(req uired) CDS YS is an e xisting co ding syste m of the I NSTITUTION file (#4) . To see t he existin g coding s ystem in t he file:
	5247	>D CDSYS^X UAF4(.Y)
	5248	id:(requir ed) ID is the identi fier assoc iated with the codin g system. The statio n number, for exampl e, is the identifier for the V ASTANUM co ding syste m and NPI number is the ID for the NPI c oding syst em.
	5249	Output:ret urns:Retur ns the Int ernal Entr y Number ( IEN) of th e institut ion reques ted.
	5250
	5251	MAIN^XUMFI (): HL7 Ma ster File Message Bu ilder
	5252	Reference Type:Contr olled Subs cription
	5253	Category:I nstitution File
	5254	ICR #:2171
	5255	Descriptio n:This API implement s an HL7 M aster File Message B uilder Int erface tha t dynamica lly maps a VA FileMa n field to an HL7 Ma ster File sequence w ithin a se gment. The interface implement s function ality to b uild Maste r File Not ification (MFN), Mas ter File Q uery (MFQ) , and Mast er File Re sponse (MF R) segment s. The int erface cal ls applica ble VISTA HL7 GENERA TE and GEN ACK interf aces to se nd/reply/b roadcast a n appropri ate HL7 Ma ster File message.
	5256	Format:MAI N^XUMFI(if n,ien,type ,param,err or)
	5257	Input Para meters:See MAIN^XUMF PFor a des cription o f the Inpu t paramete rs for thi s API, see the “MAIN ^XUMFP(): Master Fil e Paramete rs" API.
	5258	Output Par ameters
	5259	& Output:S ee MAIN^XU MFPFor a d escription of the Ou tput Param eters and Output for this API, see the “ MAIN^XUMFP (): Master File Para meters" AP I.
	5260
	5261	Details
	5262	This inter face shoul d be calle d after th e Master F ile Parame ter API. T he Master File Param eter API s ets up the required parameters in the PA RAM array.
	5263	The Instit ution File Redesign (IFR) patc h (i.e., X U8.0206) implement s several applicatio n Program Interfaces (APIs). A fter the I FR patch h as been in stalled an d the Clea nup perfor med, the S TATION NUM BER field (#99) is a unique ke y to the I NSTITUTION file (#4) .
	5264	Example
	5265	>D MAIN^XU MFI(4,1872 3,1,.PARAM ,.ERROR)
	5266
	5267	From the H L7 MESSAGE TEXT file (#772), y ou would s ee the fol lowing:
	5268	Figure 43: MAIN^XUMF I API—Samp le output
	5269	DATE/TIME ENTERED: J AN 12, 200 1@09:17:29
	5270	SERVER AP PLICATION: XUMF MFN T RANSMISSIO N TYPE: OU TGOING
	5271	MESSAGE I D: 0259 P ARENT MESS AGE: JAN 1 2, 2001@09 :17:29
	5272	PRIORITY: DEFERRED R ELATED EVE NT PROTOCO L: XUMF MF N
	5273	MESSAGE T YPE: SINGL E MESSAGE
	5274	MESSAGE TE XT:
	5275	MFI^Z04^MF S^REP^2001 0112091729 ^200101120 91729^NE
	5276	MFE^MUP^^1 9001011^63 1GD~STATIO N NUMBER~D
	5277	ZIN^GREENF IELD^631GD ^National^ CBOC~FACIL ITY TYPE~V A^^^MASSAC HUSETTS^^^ ^^^
	5278	STATUS: S UCCESSFULL Y COMPLETE D
	5279	DATE/TIME PROCESSED : JAN 12, 2001@09:17 :29
	5280	NO. OF CH ARACTERS I N MESSAGE: 161 N O. OF EVEN TS IN MESS AGE: 1
	5281
	5282	MAIN^XUMFP (): Master File Para meters
	5283	Reference Type:Contr olled Subs cription
	5284	Category:I nstitution File
	5285	ICR #:2171
	5286	Descriptio n:This API sets up r equired pa rameters u sed by the HL7 Maste r File Mes sage Build er Interfa ce and the HL7 Maste r File mes sage handl er. The in terface de fines requ ired param eters and serves as a common i nterface f or paramet er initial ization. T his interf ace is the enabling component of the Mas ter File S erver (MFS ) mechanis m allowing VA FileMa n Master F iles to be maintaine d by the s erver, inc luding fil es with mu ltiple fie lds and ex tended ref erences.
	5287	The develo per can se t any PARA M paramete r before o r after th e interfac e call and override the defaul t value.
	5288	Format:MAI N^XUMFP(if n,ien,type ,param,err or)
	5289	Input Para meters:ifn :(required ) Internal File Numb er (IFN).
	5290	ien:(requi red) Inter nal Entry Number (IE N).
	5291	Single ent ry (pass b y value).
	5292	Example:
	5293	IEN=1
	5294	Multiple e ntries (pa ss by refe rence).
	5295	Example:
	5296	IEN(1)=“”
	5297	IEN(2)=“”
	5298	ALL nation al entries (pass by value).
	5299	Example:
	5300	IEN=“ALL”
	5301	type:(requ ired) Mess age TYPE. Possible v alues are:
	5302	0—MFN: Uns olicited u pdate.
	5303	1—MFQ: Que ry particu lar record and file.
	5304	3—MFQ: Que ry particu lar record in array.
	5305	5—MFQ: Que ry group r ecords fil e.
	5306	7—MFQ: Que ry group r ecords arr ay.
	5307	11—MFR: Qu ery respon se particu lar record file.
	5308	13—MFR: Qu ery respon se particu lar record array.
	5309	15—MFR: Qu ery respon se group r ecords fil e.
	5310	17—MFR: Qu ery respon se group r ecords arr ay.
	5311	Output Par ameterspar am(“PROTOC OL”):IEN P ROTOCOL fi le (#101).
	5312	param(“BRO ADCAST”):B roadcast m essage to all VistA sites.
	5313	param(“LLN K”):Logica l link in HLL(“LINKS ”,n) forma t.
	5314	Output:err or:1^Error message t ext
	5315
	5316	Details
	5317	Table 4: M AIN^XUMFP( ): Master File Param eters API— QRD: Query Definitio n
	5318	Parameter
	5319	HL7 Sequen ce
	5320	HL7 Data T ype
	5321	param(“QDT ”)
	5322	Query Date /Time
	5323	TS
	5324	param(“QFC ”)
	5325	Query Form at Code
	5326	ID
	5327	param(“QP” )
	5328	Query Prio rity
	5329	ID
	5330	param(“QID ”)
	5331	Query ID
	5332	ST
	5333	param(“DRT ”)
	5334	Deferred R esponse Ty pe
	5335	ID
	5336	param(“DRD T”)
	5337	Deferred R esponse Da te/Time
	5338	TS
	5339	param(“QLR ”)
	5340	Quantity L imited Req uest
	5341	CQ
	5342	param(“WHO ”)
	5343	Who Subjec t Filter
	5344	XCN
	5345	param(“WHA T”)
	5346	What Subje ct Filter
	5347	CE
	5348	param(“WDD C”)
	5349	What Depar tment Data Code
	5350	CE
	5351	param(“WDC VQ”)
	5352	What Data Code Value Qual.
	5353	CM
	5354	param(“QRL ”)
	5355	Query Resu lts Level
	5356	ID
	5357
	5358	Table 5: M AIN^XUMFP( ): Master File Param eters API— XCN Data T ype of QRD WHO Param eter
	5359	Component
	5360	Value
	5361	Descriptio n
	5362	1ST compon ent
	5363
	5364	One of the following :
	5365	NAME
	5366
	5367	Value of N AME field (#.01) for Internal Entry Numb er (IEN).
	5368	ALL
	5369
	5370	String rep resents al l national entries.
	5371	IEN ARRAY
	5372
	5373	String rep resents en tries pass ed in IEN array.
	5374	9th compon ent
	5375	D
	5376	Source tab le (VA Fil eMan cross -reference ).
	5377	10th compo nent
	5378	045A4
	5379	Assigning authority.
	5380
	5381	Table 6: M AIN^XUMFP( ): Master File Param eters API— CE Data Ty pe of QRD WHAT Param eter
	5382	Component
	5383	Value
	5384	Descriptio n
	5385	1ST compon ent
	5386	4
	5387	Identifier
	5388	2nd compon ent
	5389	IFN
	5390	Text
	5391	3rd compon ent
	5392	VA FM
	5393	Name of Co ding Syste m
	5394
	5395	Table 7: M AIN^XUMFP( ): Master File Param eters API— MFI: Maste r File Ide ntificatio n
	5396	Parameter
	5397	Descriptio n
	5398	PARAM(“MFI ”)
	5399	Master Fil e Identifi er
	5400	PARAM(“MFA I”)
	5401	Master Fil e Applicat ion Identi fier
	5402	PARAM(“FLE C”)
	5403	File-Level Event Cod e
	5404	PARAM(“END T”)
	5405	Entered Da ta/Time
	5406	PARAM(“MFI EDT”)
	5407	Effective Date/Time
	5408	PARAM(“RLC ”)
	5409	Response L evel Code
	5410
	5411	Table 8: M AIN^XUMFP( ): Master File Param eters API— MFE: Maste r File Ent ry
	5412	Parameter
	5413	Descriptio n
	5414	PARAM(“RLE C”)
	5415	Record-Lev el Event C ode
	5416	PARAM(“MFN CID”)
	5417	MFN Contro l ID
	5418	PARAM(“MFE EDT”)
	5419	Effective Date/Time
	5420	PARAM(“PKV ”)
	5421	Primary Ke y Value
	5422
	5423	Table 9: M AIN^XUMFP( ): Master File Param eters API— [Z...] Seg ments Para meters
	5424	Parameter
	5425	Descriptio n
	5426	PARAM(“SEG ”,SEG)=“”
	5427	HL7 segmen t name
	5428	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,FLD# )
	5429	segment se quence # a nd field
	5430
	5431	NOTE: If a ny special processin g is requi red, in ad dition to the extern al value p assed by V A FileMan, set the F LD# node e qual to a formatting function “n^$$TAG^R TN(X)”.
	5432	“n” being the compon ent sequen ce number.
	5433	“X” repres enting the external value from VA FileMa n.
	5434	P(segment_ sequence,H LCS,n)=FM_ external_v alue.
	5435
	5436	Table 10: MAIN^XUMFP (): Master File Para meters API —Files Inv olving Sub -records a nd Extende d Referenc e
	5437	Parameter
	5438	Descriptio n
	5439	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,“FIL E”)
	5440	See VA Fil eMan docum entation.
	5441	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,“IEN S”)
	5442	$$GET1^DIQ () for val ue.
	5443	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,“FIE LD”)
	5444	of FILE, I ENS, & FIE LD.
	5445	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,“KEY ”)
	5446	.01 value.
	5447	PARAM(“SEG ”,SEG,“SEQ ”,SEQ,“FOR MAT”)
	5448	format non ST data t ypes.
	5449
	5450	NOTE: Quer y group re cords stor e PARAM in the ^TMP global wit h the foll owing root : ^TMP(“XU MF MFS”,$J ,“PARAM”,I EN).Exampl e: MFE PKV node is ^ TMP(“XUMF MFS”,$J,“P ARAM”,IEN, “PKV”)
	5451	Example
	5452	The follow ing exampl e is a que ry (MFQ) f or a group records a rray:
	5453
	5454	>D MAIN^XU MFP(4,“ALL ”,7,.PARAM ,.ERROR)
	5455	Since quer y group re cords stor e PARAM in the ^TMP global, di splay the ^TMP globa l to see t he PARAM v alues:
	5456	Figure 44: MAIN^XUMF P API—Disp laying ^TM P global f or PARAM v alues
	5457	>D ^%G
	5458
	5459	Global ^TM P(“XUMF MF S”,$J
	5460	TM P(“XUMF MF S”,$J
	5461	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“DRDT” ) =
	5462	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“DRT”) =
	5463	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“ENDT” ) =
	5464	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“FLEC” ) = UPD
	5465	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“MFAI” ) =
	5466	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“MFEED T”) = 2001 0212110654
	5467	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“MFI”) = Z04
	5468	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“MFIED T”) =
	5469	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“MFNCI D”) =
	5470	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“POST” ) = POST^X UMFP4C
	5471	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“PRE”) = PRE^XUM FP4C
	5472	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“PROTO COL”) = 22 33
	5473	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QDT”) = 2001021 2110654
	5474	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QFC”) = R
	5475	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QID”) = Z04 ARR AY
	5476	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QLR”) = RD~999
	5477	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QP”) = I
	5478	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“QRL”) =
	5479	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“RLC”) = NE
	5480	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“RLEC” ) = MUP
	5481	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,1,.01) = ST
	5482	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,2,99) = ST
	5483	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,3,11) = ID
	5484	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,4,13) = CE^~FACILI TY TYPE~VA
	5485	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,5,100) = ST
	5486	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,6,101) = ST
	5487	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,7,.02) = ST
	5488	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,8,“DTYP” ) = CE^~VI SN~VA
	5489	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,8,“FIELD ”) = 1
	5490	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,8,“FILE” ) = 4.014
	5491	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,8,“IENS” ) = 1,?+1,
	5492	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,9,“DTYP” ) = ST
	5493	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,9,“FIELD ”) = 1:99
	5494	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,9,“FILE” ) = 4.014
	5495	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,9,“IENS” ) = 2,?+1,
	5496	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,10,“DTYP ”) = DT
	5497	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,10,“FIEL D”) = .01
	5498	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,10,“FILE ”) = 4.999
	5499	^TMP(“XUMF MFS”,5390 17563, PAR AM”,“SEG”, “ZIN”,“SEQ ”,11,“DTYP ”) = ST
	5500	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,11,“FIEL D”) = .06: 99
	5501	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,11,“FILE ”) = 4.999
	5502	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,12,“DTYP ”) = DT
	5503	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,12,“FIEL D”) = .01
	5504	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,12,“FILE ”) = 4.999
	5505	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,13,“DTYP ”) = ST
	5506	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,13,“FIEL D”) = .05: 99
	5507	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEG”, “ZIN”,“SEQ ”,13,“FILE ”) = 4.999
	5508	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“SEGME NT”) = ZIN
	5509	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“WDCVQ ”) =
	5510	^TMP(“XUMF MFS”,5390 17563,“PAR AM”,“WDDC” ) = INFRAS TRUCTURE~I NFORMATION INFRASTRU CTURE ~VA TS
	5511	^TMP(“XUMF MFS”,5390 17563,”PAR AM”,“WHAT” ) = 4~IFN~ VA FM
	5512	^TMP(“XUMF MFS”,5390 17563,”PAR AM”,“WHO”) = ALL~~~~ ~~~~D~045A 4
	5513
	5514
	5515	Kernel Ins tallation and Distri bution Sys tem (KIDS) : Develope r Tools
	5516	KIDS Build -related O ptions
	5517	To get to the KIDS: Kernel Ins tallation & Distribu tion Syste m menu [XP D MAIN] (l ocked with the XUPRO G security key) choo se the Pro grammer Op tions menu option [X UPROG] on the Kernel Systems M anager Men u [EVE], a s shown be low:
	5518	Figure 45: KIDS—Edit s and Dist ribution m enu option s
	5519	Select Sys tems Manag er Menu Op tion: PROG RAMMER OPT IONS
	5520
	5521	KIDS Kernel Ins tallation & Distribu tion Syste m ...[XPD MAIN]
	5522	**> Loc ked with X UPROG
	5523	NTEG Build an ‘ NTEG’ rout ine for a package
	5524	PG Programmer mode
	5525	ALS MENU T EXT SAMPLE ...
	5526	Calculate and Show C hecksum Va lues
	5527	Delete Unr eferenced Options
	5528	Error Proc essing ...
	5529	Global Blo ck Count
	5530	List Globa l
	5531	M Pointer Relations
	5532	Number bas e changer
	5533	Routine To ols ...
	5534	Test an op tion not i n your men u
	5535	Verifier T ools Menu ...
	5536
	5537	Select Pro grammer Op tions Opti on: KIDS < Enter> Ke rnel Insta llation & Distributi on
	5538	System
	5539
	5540	Edits and Distributi on ...[XPD DISTRIBUT ION MENU]
	5541	Utilities ...[XPD UT ILITY]
	5542	Installati on ...[XPD INSTALLAT ION MENU]
	5543	**> Loc ked with X UPROGMODE
	5544	Select Ker nel Instal lation & D istributio n System O ption: EDI TS AND DIS TRIBUTION
	5545
	5546
	5547	Create a B uild Using Namespace
	5548	Copy Build to Build
	5549	Edit a Bui ld
	5550	Transport a Distribu tion
	5551	Old Checks um Update from Build
	5552	Old Checks um Edit
	5553	Routine Su mmary List
	5554	Version Nu mber Updat e
	5555
	5556	Select Edi ts and Dis tribution Option:
	5557
	5558	Creating B uilds
	5559	KIDS intro duces sign ificant re visions to the proce ss of expo rting soft ware appli cations ov er the pre vious expo rt mechani sm, DIFROM .
	5560	REF: For a n introduc tion to KI DS and a d escription of the KI DS install ation and utility op tions, see the “KIDS : System M anagement— Installati ons” and “ KIDS: Syst em Managem ent—Utilit ies” secti ons in the Kernel Sy stems Mana gement Gui de.
	5561	A function al listing of the KI DS options supportin g software applicati on (packag e) export is shown b elow:
	5562	Table 11: KIDS—Optio ns support ing softwa re applica tion build s and expo rts
	5563	Task Categ ory
	5564	Option Nam e
	5565	Option Tex t
	5566	Create Bui ld Entry
	5567	XPD BUILD NAMESPACE
	5568	Create a B uild using Namespace
	5569
	5570	XPD COPY B UILD
	5571	Copy Build to Build
	5572
	5573	XPD EDIT B UILD
	5574	Edit a Bui ld
	5575	Create a D istributio n
	5576	XPD TRANSP ORT PACKAG E
	5577	Transport a Distribu tion
	5578
	5579	This secti on covers each of th ese tasks, describin g how to a ccomplish the tasks using KIDS options.
	5580	Build Entr ies
	5581	KIDS store s the defi nition of a software applicati on in the BUILD file (#9.6). I ndividual entries in the BUILD file (#9. 6) are cal led build entries, o r builds f or short. To export a software applicati on, you mu st first d efine a bu ild entry for it in the BUILD file (#9.6 ).
	5582	Unlike DIF ROM, where you re-us ed the sam e PACKAGE file (#9.4 ) entry ea ch time yo u exported a new ver sion of a software a pplication , with KID S you crea te a new B UILD file (#9.6) ent ry each ti me you exp ort a soft ware appli cation ver sion. One advantage of having one BUILD entry per software a pplication version i s that you have a co mplete his tory of ea ch version of your s oftware ap plication, which mak es it easi er to comp are previo us version s of a sof tware appl ication wi th the cur rent versi on.
	5583	After you create the build nam e, KIDS gi ve you the option to choose th e type of build you are creati ng. There are three types from which to choose:
	5584	Single
	5585	Multi-Pack age
	5586	Global
	5587	Figure 46: KIDS—Choo sing a bui ld type sa mple
	5588	Select Edi ts and Dis tribution Option: ED IT A BUILD
	5589	Select BUI LD NAME: T EST 5.0
	5590	Are you adding ‘TE ST 5.0’ as a new BUI LD (the 10 4TH)? Y <E nter> (Yes )
	5591	BUILD P ACKAGE FIL E LINK: RE T
	5592	BUILD T YPE: SINGL E PACKAGE/ / ?
	5593	Choos e from:
	5594	0 SING LE PACKAGE
	5595	1 MULT I-PACKAGE
	5596	2 GLOB AL PACKAGE
	5597	BUILD T YPE: SINGL E PACKAGE/ / GLOBAL < Enter> GL OBAL PACKA GE
	5598
	5599	The follow ing KIDS o ptions, de scribed be low, suppo rt creatin g and main taining bu ild entrie s:
	5600	Create a B uild Using Namespace
	5601	Copy Build to Build
	5602	Edit a Bui ld
	5603	Create a B uild Using Namespace
	5604	You can qu ickly crea te a build entry and populate its compon ents by na mespace. T he Create a Build Us ing Namesp ace option searches for all co mponents i n the curr ent databa se matchin g a given list of na mespaces ( you can ex clude by n amespace a lso). The option sea rches for components of every type that match the namespaces and popul ates the b uild entry with all matches it finds on the system . You can then use E dit a Buil d to fine- tune the b uild entry .
	5605	As well as creating a new buil d entry, y ou can use this opti on to popu late an ex isting bui ld entry b y namespac e. In this case, you are asked if you wa nt to purg e the exis ting data. If you an swer YES, the option purges th e build co mponents i n the entr y, and the n populate s the buil d componen ts by name space. If you answer NO, the o ption merg es all com ponents ma tching the selected namespaces into the existing b uild entry ; it remov es nothing already i n the curr ent build entry.
	5606	The follow ing are Ke rnel 8.0 c omponent t ypes (list ed alphabe tically):
	5607	Bulletin
	5608	Dialog
	5609	Form
	5610	Function
	5611	Help Frame
	5612	HL7 Applic ation Para meter
	5613	HL Logical Link
	5614	HL Lower L evel Proto col
	5615	Input Temp late
	5616	List Templ ate
	5617	Mail Group
	5618	Option
	5619	Print Temp late
	5620	Protocol
	5621	Remote Pro cedure
	5622	Routine
	5623	Security K ey
	5624	Sort Templ ate
	5625	Figure 47: KIDS—Popu lating a b uild entry by namesp ace
	5626	Select Edi ts and Dis tribution Option: CR EATE A BUI LD USING N AMESPACE
	5627
	5628	Select BUI LD NAME: Z XGY 1.0
	5629	Are you adding ‘ZX GY 1.0’ as a new BUI LD (the 14 th)? YES
	5630	BUILD P ACKAGE FIL E LINK: <E nter>
	5631
	5632
	5633	Namespace: ZXG
	5634	Namespace: -ZXGI
	5635	Namespace: <Enter>
	5636
	5637	NAMESPACE INCLUDE EXCLU DE
	5638	------- ----- --
	5639	ZXG ZXGI
	5640
	5641	OK to cont inue? YES/ / <Enter>
	5642	...SORRY, LET ME THI NK ABOUT T HAT A MOME NT...
	5643
	5644	...Don e.
	5645
	5646	Figure 48: KIDS—Copy ing a buil d entry
	5647	Select Edi ts and Dis tribution Option: CO PY BUILD T O BUILD
	5648
	5649	Copy FROM what Packa ge: ZXG TE ST 1.0
	5650	Copy TO wh at Package : ZXG TEST 1.1
	5651	ARE YOU ADDING ‘ZX G TEST 1.1 ’ AS A NEW BUILD (TH E 5TH)? Y <Enter> (Y ES)
	5652	BUILD P ACKAGE FIL E LINK: <E nter>
	5653
	5654	OK to cont inue? YES/ / <Enter>
	5655	...HMMM, L ET ME PUT YOU ON ‘HO LD’ FOR A SECOND... ...Done .
	5656
	5657	Copy Build to Build
	5658	You can cr eate a new build ent ry based o n a previo us entry u sing the C opy Build to Build o ption. Wit h KIDS, yo u must cre ate a new build entr y for each new versi on of a so ftware app lication. This optio n gives yo u a way to quickly c opy a prev ious build entry to a new entr y. You can then use the Edit a Build to fine-tune the copied build ent ry.
	5659	If you cho ose an exi sting entr y to copy into, the option pur ges the ex isting ent ry first b efore copy ing into i t.
	5660	Edit a Bui ld
	5661	Using the Edit a Bui ld option, you can c reate new build entr ies and ed it all par ts of exis ting build entries. Edit a Bui ld is a VA FileMan S creenMan-d riven opti on. There are four m ain screen s in the E dit a Buil d. The fol lowing sec tions desc ribe in de tail each part of a build entr y and how you can ed it each pa rt.
	5662	KIDS Build Screens
	5663	KIDS Build Screens a re designe d in conju nction wit h the Edit a Build o ption to h elp you pl an your bu ild entrie s.
	5664	Table 12: KIDS—Funct ional layo ut, Edit a Build
	5665	Screen
	5666	Build Sect ion
	5667	Build Sub- Section
	5668	Screen 1
	5669	Build Name
	5670
	5671
	5672	Date Distr ibuted
	5673
	5674
	5675	Descriptio n
	5676
	5677
	5678	Environmen t Check Ro utine
	5679
	5680
	5681	Pre-Instal l Routine
	5682
	5683
	5684	Post-Insta ll Routine
	5685
	5686
	5687	Pre-Transp ortation R outine
	5688
	5689	Screen 2
	5690	Files and Data
	5691	Partial DD Definitio n
	5692
	5693
	5694	Send Data Definition
	5695	Screen 3
	5696	Build Comp onents
	5697	Print Temp late
	5698
	5699
	5700	Sort Templ ate
	5701
	5702
	5703	Input Temp late
	5704
	5705
	5706	Form
	5707
	5708
	5709	Function
	5710
	5711
	5712	Dialog
	5713
	5714
	5715	Bulletin
	5716
	5717
	5718	Mail Group
	5719
	5720
	5721	Help Frame
	5722
	5723
	5724	Routine
	5725
	5726
	5727	Option
	5728
	5729
	5730	Security K ey
	5731
	5732
	5733	Protocol
	5734
	5735
	5736	List Templ ate
	5737
	5738
	5739	HL7 Applic ation Para meter
	5740
	5741
	5742	HL Lower L evel Proto col
	5743
	5744
	5745	HL Logical Link
	5746
	5747
	5748	Remote Pro cedure
	5749	Screen 4
	5750	Install Qu estions
	5751
	5752
	5753	Required B uilds
	5754
	5755
	5756	Package Fi le Link
	5757
	5758
	5759	Package Tr acking
	5760
	5761
	5762	Edit a Bui ld: Name & Version, Build Info rmation
	5763	When you i nvoke the Edit a Bui ld option, KIDS load s a four-p age Screen Man form. The first screen of the form l ets you ed it the fol lowing sof tware appl ication se ttings:
	5764	Name
	5765	Date Distr ibuted
	5766	Descriptio n
	5767	Environmen t Check Ro utine
	5768	Pre-Instal l Routine
	5769	Post-Insta ll Routine
	5770	Pre-Transp ortation R outine
	5771	Build Name
	5772	The name o f a build entry is w here KIDS stores bot h the soft ware appli cation’s n ame and ve rsion numb er. The bu ild name m ust be a s oftware ap plication name, foll owed by a space and then follo wed by a v ersion num ber. This means that every ver sion of a software a pplication requires a separate entry in the BUILD file (#9.6 ). One way that this is an adv antage is that you h ave a reco rd of the contents o f every ve rsion of a software applicatio n that you export.
	5773	Figure 49: KIDS—Scre en 1 of Ed it a Build sample
	5774	Edi t a Build PAGE 1 OF 5
	5775	Name: ZXG Test 1.0 TYPE: SINGLE PAC KAGE
	5776	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5777
	5778	Name: ZX G DEMO 1.0
	5779
	5780	Date Distr ibuted: AU G 29,2004
	5781
	5782	Descr iption: Dele te Routine
	5783	aft er install
	5784	Environme nt Check R outine: Y/ N:
	5785
	5786	Pre -Install R outine: ZX GPRE Y/ N: N
	5787
	5788	Post -Install R outine: ZX GPOS Y/ N: N
	5789
	5790	Pre-Transp ortation R outine:
	5791	__________ __________ __________ __________ __________ __________ __________ _________
	5792
	5793
	5794	COMMAND: Pre ss <PF1>H for help Insert
	5795
	5796	Edit a Bui ld: Files
	5797	The second screen of Edit a Bu ild is whe re you ent er all the files to export wit h your sof tware appl ication. F or each fi le, you ca n choose w hether or not to sen d data wit h the file definitio n.
	5798	Data Dicti onary Upda te
	5799	The instal ling site is not ask ed whether they want to overri de data di ctionary u pdates; da ta diction ary update s are dete rmined ent irely by h ow the dev eloper exp orts the f ile. There are two s ettings in KIDS you can use to determine whether K IDS should update a file’s dat a dictiona ry at the installing site:
	5800	YES—If you answer YE S to Updat e the Data Dictionar y, the dat a dictiona ry is upda ted at the installin g site.
	5801	NO—If you answer NO to Update the Data D ictionary, the only time the d ata dictio nary is up dated is i f the file does not exist on t he install ing system .
	5802	You can en ter M code in the Sc reen to De termine DD Update fi eld. The c ode should set the v alue of $T . If $T is true, KID S installs the data dictionary ; if $T=0, KIDS does not. The screen is only execu ted if the data dict ionary alr eady exist s on the i nstalling system, ho wever; if the data d ictionary does not a lready exi st, the fi le is inst alled unco nditionall y (the scr een is not executed) . You can use the co de in this field, fo r example, to examin e the targ et environ ment to de termine wh ether to u pdate a da ta diction ary (provi ding the d ata dictio nary alrea dy exists) .
	5803	Sending Se curity Cod es
	5804	With KIDS, you can s pecify on a file-by- file basis whether t o send sec urity code s. For eac h file, yo u can set SEND SECUR ITY CODE t o either Y ES or NO.
	5805	If you ans wer YES to send secu rity codes , KIDS sen ds the sec urity code s of the f iles on th e developm ent system . KIDS onl y updates security c odes at th e installi ng site on new files (i.e., fi les that d o not alre ady exist) , however. Security codes for a file are not updat ed at the installing site if t he file al ready exis ts.
	5806	NOTE: Use VA FileMan ’s FILESEC ^DDMOD API to set th e security access co des for an existing file.REF: For more i nformation on the FI LESEC^DDMO D API, see Section 3 in the VA FileMan D eveloper’s Guide loc ated on th e VDL at: http://www 4. DOMAIN /vdl/appli cation.asp ?pid=5
	5807	Figure 50: KIDS—Scre en 2 of Ed it a Build : Selectin g files
	5808	Edi t a Build PAGE 2 OF 5
	5809	Name: ZXG Test 1.0 TYPE: SINGLE PAC KAGE
	5810	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5811	Fil e List (Na me or Numb er
	5812
	5813	NEW P ERSON
	5814
	5815
	5816	__________ __________ __________ __________ __________ __________ __________ _________
	5817
	5818
	5819	COMMAND: Pre ss <PF1>H for help Insert
	5820
	5821	Figure 51: KIDS—Data dictionar y and data settings
	5822	Edi t a Build PAGE 2 OF 5
	5823	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	5824	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5825	Fil e List (N ame or Num ber)
	5826	┌───────── ────────── ────── DD Export Opt ions ───── ────────── ────────── ───────┐
	5827	│ │
	5828	│ File: N EW PERSON │
	5829	│ │
	5830	│ Send F ull or Par tial DD... : PARTIAL │
	5831	│ │
	5832	│Update th e Data Dic tionary: Y ES Send Secu rity Code: NO │
	5833	│ │
	5834	│Screen to Determine DD Update │
	5835	│ │
	5836	│ │
	5837	│ Dat a Comes Wi th File... : YES │
	5838	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	5839	__________ __________ __________ __________ __________ __________ __________ _________
	5840
	5841
	5842	COMMAND: Pre ss <PF1>H for help Insert
	5843
	5844	Sending Fu ll or Part ial Data D ictionarie s
	5845	KIDS suppo rts sendin g out full data dict ionaries ( the entire file defi nition), a nd partial data dict ionaries ( specified fields in a file).
	5846	Full DD (A ll Fields)
	5847	To send th e entire d ata dictio nary, answ er FULL at the Send Full or Pa rtial DD p rompt. In this case, all field definitio ns are exp orted. If you are se nding data , you must export th e FULL dat a dictiona ry.
	5848	Partial DD (Some Fie lds)
	5849	You can on ly send a partial DD if the fi le already exists at the site. If you an swer PARTI AL at the “Send Full or Partia l DD” prom pt, KIDS l ets you ch oose what data dicti onary leve ls to expo rt.
	5850	In the Dat a Dictiona ry Number popup wind ow (Figure 53), you can select either on e of the f ollowing t ypes:
	5851	File Numbe r—Top leve l of the f ile.
	5852	Multiple—S ub-data di ctionary n umber (als o known as a subfile ). You can export an y Multiple , no matte r how deep (every Mu ltiple’s d ata dictio nary numbe r is selec table).
	5853	File Numbe r Level
	5854	In the Fie ld Number popup wind ow (Figure 54), if y ou selecte d the file number ty pe, you ca n select w hich field s to expor t at that data dicti onary leve l:
	5855	If you do not specif y any fiel ds, no fie lds are se nt.
	5856	If you do specify fi elds, only the speci fied field s are sent . You cann ot choose any multip les at thi s data dic tionary le vel.
	5857	Multiple L evel
	5858	In the Fie ld Number popup wind ow (Figure 54), if y ou selecte d the Mult iple (sub- data dicti onary numb er) type, you can se lect which fields to export at that sub- data dicti onary leve l:
	5859	If you do not specif y any fiel ds, all fi elds are s ent. All f ields at t his level and their descendant s are expo rted. You must do th is if the multiple i s new at t he site.
	5860	If you do specify fi elds, only the speci fied field s are sent .
	5861	Unlike DIF ROM, KIDS does not r equire sen ding the . 01 field o f the file if you se nd a parti al data di ctionary.
	5862	Whenever y ou export a multiple , all “par ents” of t he multipl e all the way up to the .01 fi eld of the file must exist at the instal ling site, or else y ou must ex port all “ parents” ( higher dat a dictiona ry levels) yourself. Otherwise , the mult iple is no t installe d.
	5863	NOTE: Cert ain attrib utes (Iden tifiers, “ ID” nodes, etc.) are considere d file att ributes (a s opposed to field a ttributes) , and so a re sent on ly when yo u send a f ull DD. Th ey are not sent with a partial DD.
	5864	Figure 52: KIDS—Data dictionar y settings screen—DD Export Op tions
	5865	Edi t a Build PAGE 2 OF 5
	5866	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	5867	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5868	Fil e List (N ame or Num ber)
	5869	┌───────── ────────── ────── DD Export Opt ions ───── ────────── ────────── ───────┐
	5870	│ │
	5871	│ File: N EW PERSON │
	5872	│ │
	5873	│ Send F ull or Par tial DD... : PARTIAL │
	5874	│ │
	5875	│Update th e Data Dic tionary: Y ES Send Secu rity Code: NO │
	5876	│ │
	5877	│Screen to Determine DD Update │
	5878	│ │
	5879	│ │
	5880	│ Dat a Comes Wi th File... : YES │
	5881	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	5882	__________ __________ __________ __________ __________ __________ __________ _________
	5883
	5884
	5885	COMMAND: Pre ss <PF1>H for help Insert
	5886
	5887	Figure 53: KIDS—Part ial DD: Ch oosing DD levels (to p level an d Multiple ) to send; Data Dict ionary Num ber level
	5888	Edi t a Build PAGE 2 OF 5
	5889	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	5890	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5891	Fil e List (N ame or Num ber)
	5892	┌───────── ────────── ────── DD Export Opt ions ───── ────────── ────────── ───────┐
	5893	│┌──────── ────────── ────── Dat a Dictiona ry Number ────────── ────────── ──────┐│
	5894	││ NEW PER SON (File- top level) ││
	5895	││ DMMS UN ITS (sub-f ile) ││
	5896	││ ALIAS ( sub-file) ││
	5897	││ DEFINED FORMATS F OR LM (sub -file) ││
	5898	││ ││
	5899	││ ││
	5900	││ ││
	5901	││ ││
	5902	││ ││
	5903	│└──────── ────────── ────────── ────────── ────────── ────────── ────────── ──────┘│
	5904	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	5905	__________ __________ __________ __________ __________ __________ __________ _________
	5906
	5907
	5908	COMMAND: Pre ss <PF1>H for help Insert
	5909
	5910	Figure 54: KIDS—Part ial DD: Ch oosing DD levels (to p level an d Multiple ) to send; Field Num ber level
	5911	Edi t a Build PAGE 2 OF 5
	5912	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	5913	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5914	Fil e List (N ame or Num ber)
	5915	┌───────── ────────── ────── DD Export Opt ions ───── ────────── ────────── ───────┐
	5916	│┌──────── ────────── ────── Dat a Dictiona ry Number ────────── ────────── ──────┐│
	5917	││┌─────── ────────── ────── Fie ld Number ────────── ────────── ────────── ─────┐││
	5918	│││ TEST │││
	5919	│││ │││
	5920	│││ │││
	5921	│││ │││
	5922	│││ │││
	5923	│││ │││
	5924	│││ │││
	5925	││└─────── ────────── ────────── ────────── ────────── ────────── ────────── ─────┘││
	5926	│└──────── ────────── ────────── ────────── ────────── ────────── ────────── ──────┘│
	5927	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	5928
	5929
	5930	COMMAND: Pre ss <PF1>H for help Insert
	5931
	5932	Choosing W hat Data t o Send wit h a File
	5933	When you s end data, you can se nd all of the data i n a file; however, K IDS also l ets you se nd a subse t of a fil e’s data t o installi ng sites.
	5934	In the Scr een to Sel ect Data f ield, you can enter M code to screen dat a. The M c ode should set $T; i f $T is se t to 1, th e entry is sent, and if $T is set to 0, the entry is not sen t. At the moment you r code for the scree n is execu ted, the l ocal varia ble “Y” is set to th e Internal Entry Num ber (IEN) of the ent ry being s creened, a nd the M n aked indic ator is se t to the g lobal leve l @fileroo t@(Y,0). T herefore, you can us e the valu es of “Y” and the na ked indica tor in you r screen.
	5935	In the Dat a List fie ld, you ca n select a search te mplate. Th e contents of the te mplate are the entri es that ar e exported .
	5936	If you cho ose both a screen an d a search template, the scree n is appli ed to the entries st ored in th e search t emplate.
	5937	Figure 55: KIDS—Sett ings for s ending dat a
	5938	Edi t a Build PAGE 2 OF 5
	5939	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	5940	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	5941	Fil e List (N ame or Num ber)
	5942	┌───────── ────────── ────── DD Export Opt ions ───── ────────── ────────── ───────┐
	5943	│┌──────── ────────── ────── Dat a Export O ptions ─── ────────── ────────── ──────┐│
	5944	││ Si te’s Data: OVERWRITE ││
	5945	││ ││
	5946	││ Resolve Pointers: YES May User Override D ata Update : YES ││
	5947	││ ││
	5948	││ Data List: ││
	5949	││ ││
	5950	││ Scree n to Selec t Data ││
	5951	││ ││
	5952	││ ││
	5953	│└──────── ────────── ────────── ────────── ────────── ────────── ────────── ──────┘│
	5954	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	5955	__________ __________ __________ __________ __________ __________ __________ _________
	5956
	5957
	5958	COMMAND: Pre ss <PF1>H for help Insert
	5959
	5960	Determinin g How Data is Instal led at the Receiving Site
	5961	When you s end data w ith a file , KIDS giv es you sev eral optio ns about h ow the dat a is sent. There are four ways KIDS can install fi le entries at the re ceiving si te:
	5962	Table 13: KIDS—Data installati on actions
	5963	Data Insta llation Ac tion
	5964	Descriptio n
	5965	ADD ONLY I F NEW FILE
	5966	Installs d ata at the installin g site onl y if this file is ne w to the s ite or if there is n o data in this file at the sit e.
	5967	MERGE
	5968	If no matc hing entry is found, the incom ing entry is added. When the i ncoming en try matche s an exist ing entry on the sys tem, site fields tha t are non- NULL are p reserved. Only NULL fields in a matching site entr y are over written by incoming values.
	5969	KIDS does not send o ut cross-r eferences with the d ata. When you merge the data, however, K IDS re-ind exes and c reates new cross-ref erences. A lso, when you merge the data, KIDS does not delete the old c ross-refer ences for that data.
	5970	OVERWRITE
	5971	If no matc hing entry is found, the incom ing entry is added. When the i ncoming en try matche s an exist ing entry on the sys tem, site fields tha t are non- NULL are o verwritten by incomi ng data. V alues in t he site’s fields are preserved when the incoming f ield value is NULL, however.
	5972	REPLACE
	5973	If no matc hing entry is found, the incom ing entry is added. When the i ncoming en try matche s an exist ing entry at the top level of a file, al l fields i n the exis ting entry that are fields in the incomi ng data di ctionary a re purged; then fiel d values f or the new entry are brought i n. Values in fields that are n ot part of the incom ing data d ictionary are preser ved.
	5974	KIDS does not send o ut cross-r eferences with the d ata. When you replac e the data , however, KIDS re-i ndexes and creates n ew cross-r eferences. Also, whe n you repl ace the da ta, KIDS d eletes any old cross -reference s for that data.
	5975	With multi ples, if t he .01 fie ld of an i ncoming mu ltiple mat ches the . 01 field o f an exist ing multip le, the ex isting mul tiple entr y is compl etely purg ed, and th e data fro m the inco ming multi ple replac es the cur rent multi ple entire ly; values for field s in the e xisting mu ltiple tha t are not in the inc oming data dictionar y are not restored.
	5976
	5977	You can sp ecify diff erent sett ings for s eparate fi les; withi n a file, however, a ll data mu st be inst alled in o ne of thes e four way s.
	5978	You can gi ve the ins talling si te the cho ice of ove rriding th e data upd ate. If yo u set May User Overr ide Data U pdate to Y ES, the in stalling s ite has th e choice o f whether to bring i n data tha t has been sent with this file . They are not given the choic e of how t o install data, howe ver (add o nly if new file vs. merge vs. OVERWRITE vs. REPLAC E). If you set this field to N O, the ins talling si te cannot override b ringing in data.
	5979	How KIDS M atches Inc oming Entr ies with E xisting En tries
	5980	When KIDS installs V A FileMan data, it t reats inco ming entri es differe ntly depen ding on wh ether the entry is a new entry for the f ile or the incoming entry matc hes an exi sting entr y in the f ile.
	5981	KIDS decid es if an i ncoming en try is new or matche s an exist ing entry by checkin g, in orde r:
	5982	The B inde x of the f ile or mul tiple, or the .01 fi eld if the re is no B index.
	5983	The Intern al Entry N umber (IEN ) of the e ntry (if a pplicable) .
	5984	The identi fiers of t he entry ( if applica ble).
	5985	First, KID S makes a tentative match base d on the B index. If there is no B index , KIDS goe s through the .01 fi eld entrie s of the f ile one-by -one looki ng for a m atch.
	5986	NOTE: The “B” cross- reference holds the name as a subscript. The maxim um length of subscri pts is def ined for e ach operat ing system and is st ored in th e MUMPS OP ERATING SY STEM file (#.7). KID S uses thi s length [ for exampl e, 63 (def ault) or 9 9] as the limit of c haracters to compare .
	5987	If a match (either b y the B cr oss-refere nce or by the first piece of t he zero no de) is not found, th e incoming entry is considered new and i s added to the file. If a matc h or match es are fou nd, two ad ditional c hecks are made to de termine wh ether any of the exi sting entr ies are a match.
	5988	KIDS next checks whe ther the I ENs of any tentative ly matched entries a re related . If the f ile has a defined .0 01 field, the IEN is a meaning ful attrib ute of an entry. In this case, the IENs must match . If the i nput trans form of th e .01 fiel d contains DINUM, it operates the same w ay as a .0 01 field. If the IEN is meanin gful, and no match i s found, t he incomin g entry is considere d new and is added t o the file .
	5989	If the pos sibility o f a match remains af ter checki ng IENs, K IDS perfor ms a final check bas ed on iden tifiers.
	5990	A well-des igned file uses one or more id entifiers to act as key fields , so that each entry is unique with resp ect to nam e and iden tifiers. I f identifi ers exist on either the target file or t he incomin g data dic tionary, K IDS checks the value s of all s uch identi fier field s. The val ue of each identifie r field mu st be the same for t he existin g entry an d the inco ming entry to be con sidered a match. Onl y the inte rnal value of the id entifier f ield is ch ecked (so if an iden tifier is a pointer field, pro blems coul d result). Only iden tifiers th at have va lid field numbers ar e used in this proce ss.
	5991	If there i s still mo re than on e matching entry aft er checkin g .01 fiel ds, IENs, and identi fiers, the lowest nu mbered ent ry in the site’s fil e is consi dered a ma tch for th e incoming entry for the file. On the ot her hand, if no matc h is found after che cking .01 fields, IE Ns, and id entifiers, the entry is consid ered new a nd is adde d to the f ile.
	5992	Limited Re solution o f Pointers
	5993	A feature of data ex port provi ded by KID S is resol ving point ers. For e ach file e xported wi th data, y ou can cho ose whethe r to perfo rm pointer resolutio n on that file’s poi nter field s (with th e exceptio n of .01 f ields, ide ntifier fi elds, and pointer fi elds point ing to oth er pointer fields).
	5994	KIDS does not resolv e pointers for .01 f ields and identifier fields in files or Multiples, nor field s that poi nt to othe r pointer fields. KI DS can res olve point ers, howev er, for al l other po inter fiel ds in a gi ven file o r Multiple .
	5995	When you d o not reso lve pointe rs, and th e file bei ng install ed has poi nter field s, data en tries for that file are instal led with w hatever nu merical po inter valu es are in the pointe r fields. In which c ase, there is a good chance th at the poi nter field s no longe r point to the inten ded entrie s in the p ointed to file.
	5996	Resolution of pointe rs remedie s this by exporting the FREE T EXT value of the poi nted-to en try. When KIDS has f inished in stalling a ll files a nd data en tries at t he install ing site, it begins the proces s of resol ving point ers (if an y files ar e set to h ave pointe rs resolve d).
	5997	For each f ield in an entry tha t is a poi nter field , KIDS doe s a lookup in the po inted to f ile for th e FREE TEX T value of the origi nal pointe d-to entry . If it fi nds an exa ct and uni que match, it resolv es the ori ginal poin ter by sto ring the I EN of the new matchi ng entry i n the poin ter field. If it can not find a n exact ma tch, becau se there a re no matc hing entri es or ther e are mult iple match ing entrie s, then th e pointer field is l eft blank, and KIDS displays a n error me ssage.
	5998	Resolution of pointe rs works w ith pointe d-to entri es that ar e themselv es variabl e pointers . In these cases, it stores th e file to which the pointed-to entry was pointing, and then resolves t he pointer in the ap propriate target fil e only.
	5999	Once all p ointers ar e resolved , KIDS re- indexes ea ch file. E ach time K IDS finish es resolvi ng pointer fields in a given f ile, it re -indexes t hat file.
	6000	Re-Indexin g Files
	6001	Once all n ew data ha s been add ed to all files, KID S re-index es the fil es. If any of the fi les have c ompiled cr oss-refere nces, the compiled c ross-refer ence routi nes are re built. The n, if any data was s ent for a file, KIDS re-indexe s all trad itional cr oss-refere nces and a ll new-sty le indexes with an A CTIVITY th at contain s an “I”, for all th e records in the fil e. Only th e SET logi c is execu ted.
	6002	Data Dicti onary Clea nup
	6003	If you cha nge the de finition o f a field or remove a cross-re ference, y ou must de lete the f ield or cr oss-refere nce, or ot herwise cl ean it up on the tar get accoun t during t he Pre-ins tall routi ne. You mu st complet ely purge the target site’s da ta diction ary of the old field definitio n, even if you are r e-using th e same nod e and piec e for a ne w field. T his cleanu p ensures that the d ata dictio nary does not end up with an i nconsisten t structur e after th e installa tion.
	6004	You no lon ger need t o clean up WORD PROC ESSING fie lds in the data dict ionary, ho wever. Bef ore KIDS, updated da ta diction ary field attributes stored in WORD PROC ESSING fie lds (e.g., field des cription o r technica l descript ion) did n ot complet ely overwr ite a pre- existing a ttribute w hen instal led. If th e incoming value had fewer lin es than th e pre-exis ting one, the instal l of the d ata dictio nary did n ot delete the surplu s lines au tomaticall y; this de letion had to be don e in the p re-install . KIDS, on the other hand, com pletely re places the values of WORD PROC ESSING fie lds in dat a dictiona ries.
	6005	Edit a Bui ld: Compon ents
	6006	In the thi rd screen in the Edi t a Build option, yo u can sele ct the com ponents of a softwar e applicat ion to inc lude in th e build.
	6007	KIDS lets you enter an explici t list of components for each component type. You are not re stricted b y namespac e. You can select it ems for ea ch type of component simply by choosing them. Item s can also be select ed with th e asterisk (*) wildc ard and th e exclusio n sign (-) .
	6008	To add an entry to t he list wh en a simil arly named entry alr eady exist s in the l ist, use t he normal VA FileMan conventio n of surro unding the entry wit h quotes. For exampl e, to add ZZTK to th e list whe n ZZTK1 al ready exis ts in the list, ente r “ZZTK” i n quotes.
	6009	With most component types, the permissib le install ation acti ons are:
	6010	SEND TO SI TE
	6011	DELETE AT SITE
	6012	Some compo nent types , however, have addi tional ins tallation actions av ailable; t he special cases are discussed on the fo llowing pa ges.
	6013	REF: For a list of K ernel comp onent type s, see the “Create a Build Usi ng Namespa ce”section .
	6014	Figure 56: KIDS—Scre en 3 of Ed it a Build : Componen ts
	6015	Edi t a Build PAGE 3 OF 5
	6016	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	6017	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	6018	Bui ld Compone nts
	6019
	6020	PRINT TEMP LATE (0 )
	6021	SORT TEMPL ATE (0 )
	6022	INPUT TEMP LATE (0 )
	6023	FORM (0 )
	6024	FUNCTION (0 )
	6025	DIALOG (0 )
	6026	BULLETIN (0 )
	6027	MAIL GROUP (0 )
	6028	HELP FRAME (0 )
	6029	ROUTINE (0 )
	6030	OPTION (0 )
	6031	SECURITY K EY (0 )
	6032	PROTOCOL (0 )
	6033	LIST TEMPL ATE (0 )
	6034	HL7 APPLIC ATION PARA METE (0 )
	6035	HL LOWER L EVEL PROTO COL (0 )
	6036	HL LOGICAL LINK (0 )
	6037	REMOTE PRO CEDURE (0 )
	6038	__________ __________ __________ __________ __________ __________ __________ _________
	6039
	6040
	6041	COMMAND: Pre ss <PF1>H for help Insert
	6042
	6043	NOTE: This is an exp anded view of this s creen in o rder to sh ow you all of the cu rrently av ailable co mponent ty pes. You h ave to scr oll throug h the list in order to see all of the av ailable ty pes.
	6044	Edit a Bui ld: Option s and Prot ocols
	6045	Menus and Protocols are simila r to other component types, ex cept for m enus and p rotocols, which have more than the stand ard SEND T O SITE and DELETE AT SITE inst allation a ctions.
	6046	NOTE: Begi nning with Kernel 8. 0, you can no longer send out an option with an at tached sch eduling fr equency. S cheduling of options was moved out of th e OPTION f ile (#19) and into t he OPTION SCHEDULING file (#19 .2). One a dvantage t o this is that a dev eloper’s s cheduling settings n o longer o verwrites a site’s s cheduling settings.
	6047	To indicat e to the s ite that a n option s hould be s cheduled r egularly, you should fill in t he SCHEDUL ING RECOMM ENDED fiel d for the option. Yo u can ente r YES, NO, or STARTU P. This in dicates to the site whether th ey should regularly schedule t he option or not. Yo u should l ist the ac tual frequ ency you r ecommend i n the opti on’s descr iption. Th e site can then use the TaskMa n option P rint Recom mended for Queuing O ptions to list all o ptions tha t develope rs have re commended scheduling .
	6048	Table 14: KIDS—Optio n and prot ocol insta llation ac tions
	6049	Option/Pro tocol Inst allation A ction
	6050	Descriptio n
	6051	SEND TO SI TE
	6052	Menu, opti on, or pro tocol is i nstalled a t the site ; any exis ting versi on already at the si te is comp letely pur ged before hand, exce pt those o ptions tha t are curr ently mark ed as “Out of Order” (OoO).
	6053	NOTE: The OUT OF OR DER MESSAG E field (a ka OoO fie ld) in the OPTION fi le (#19) i s updated by KIDS du ring an in stall. Whe n an optio n or proto col is sen t, KIDS al lows the s ite to dis able them during the install. That means KIDS adds the OoO f ield at th e beginnin g of the i nstall and removes i t at the e nd. In the case wher e the OoO already ex ists for a n option, KIDS does nothing. B ecause of this, KIDS does not transport the OoO fi eld. If a developer wants to a dd or chan ge an OoO, they shou ld use the OUT^XPDME NU(): Edit Option's Out of Ord er Message API durin g the post -install.
	6054	DELETE AT SITE
	6055	Menu or pr otocol is deleted at site.
	6056	USE AS LIN K FOR MENU ITEMS
	6057	Designates a menu or protocol to be used as a link . The menu or protoc ol is not exported t o the site ; instead, its name is sent so that any item you l ink to it as a menu item or pr otocol (an d send) be comes a su b-item on the corres ponding me nu or prot ocol at th e site. KI DS does no t disable options an d protocol s that hav e an Actio n of USE A S LINK FOR MENU ITEM S.
	6058	MERGE MENU ITEMS
	6059	All fields in the me nu or prot ocol excep t for item s are purg ed and rep laced by t he incomin g values f or those f ields. Any items at the site t hat do not match inc oming item s are left as is. An y items th at do matc h incoming items are completel y replaced by the in coming ite ms.
	6060	The advant age with t his action is that i t preserve s locally added item s at the s ite. The d isadvantag e is that if you hav e removed items, the removed i tems are n ot purged at the sit e.
	6061	ATTACH TO MENU
	6062	Designates an option or protoc ol, not ex ported to the site, to be atta ched to a menu that is exporte d. This is used when a menu is sent by K IDS to a s ite and th e develope r wants th e local op tion or pr otocol att ached to t he menu. T he option or protoco l is not e xported to the site; instead, its name i s sent and the local option or protocol becomes a sub-item o n the menu that is s ent.
	6063	DISABLE DU RING INSTA LL
	6064	Designates an option or protoc ol that is not expor ted to be disabled d uring the KIDS insta ll process .
	6065
	6066	Edit a Bui ld: Routin es
	6067	Routine se lection is done base d on point ers to ent ries in th e ROUTINE file (#9.8 ), but thi s file is not automa tically up dated when programs are saved and delete d on an M system. So , before a dding rout ines to a build entr y, you sho uld run KI DS’ Update Routine F ile option . Be sure to update all the ro utines and routine n amespaces that you n eed to sel ect for yo ur build.
	6068	When selec ting routi nes for th e build, y ou can sel ect indivi dual routi nes by typ ing in the ir individ ual names. You can s elect a na mespace gr oup of rou tines by u sing the * wildcard. For examp le, to inc lude all r outines in the names pace XQ, t ype in XQ* . You can exclude ro utines by inserting the - excl usion sign before ei ther a sin gle name o r a wild-c arded name space. For example, to exclude all routi nes in the XQI names pace, type -XQI*.
	6069	For each r outine, yo u can choo se one of two action s:
	6070	SEND TO SI TE (defaul t)
	6071	DELETE AT SITE
	6072	The defaul t action i s SEND TO SITE. If y ou choose DELETE AT SITE, the routine is deleted a t the inst alling sit e.
	6073	Installers of KIDS s oftware ap plications have a ch oice to up date routi nes across multiple CPUs. If t hey choose to do thi s, routine s are inst alled (or deleted) a cross all CPUs the s ite select s. KIDS di splays var ious statu s messages while eac h CPU is u pdated. Si tes cannot automatic ally insta ll routine s in the s ite’s mana ger accoun ts; howeve r, you sti ll must in struct the site to m anually in stall any routine th at goes in the manag er’s accou nt.
	6074	Figure 57: KIDS—Choo sing routi nes
	6075	Edi t a Build PAGE 2 OF 5
	6076	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	6077	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	6078	BUI LD COMPONE NTS
	6079	┌───────── ────────── ───────── ROUTINE ── ────────── ────────── ────────── ───────┐
	6080	│ │
	6081	│ +XQSRV4 SEND TO SITE │
	6082	│ XQSTCK DELET E AT SITE │
	6083	│ XQT SEND TO SITE │
	6084	│ XQT1 SEND TO SITE │
	6085	│ XQT2 SEND TO SITE │
	6086	│ XQT3 SEND TO SITE │
	6087	│ XQT4 SEND TO SITE │
	6088	│ XQTOC SEND TO SITE │
	6089	│ XQUSR SEND TO SITE │
	6090	│ │
	6091	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	6092	__________ __________ __________ __________ __________ __________ __________ _________
	6093
	6094
	6095	COMMAND: Pre ss <PF1>H for help Insert
	6096
	6097	Edit a Bui ld: Dialog Entries ( DIALOG Fil e [#.84])
	6098	VA FileMan supports the capabi lity for o ther softw are applic ations to store thei r dialog i n the VA F ileMan DIA LOG file. Some advan tages to u sing the D IALOG file (#.84) fo r user int eraction i nclude:
	6099	Separating user inte raction fr om other p rogram fun ctionality . This is a helpful step for c reating GU I interfac es.
	6100	Reusing di alog. When dialog is stored in the DIALO G file (#. 84), it ca n be re-us ed.
	6101	Easily gen erating so ftware app lication e rror lists . If error lists are stored in DIALOG fi le (#.84), there is a single p oint of ac cess to pr int a comp lete list of errors.
	6102	Implementi ng alterna te languag e interfac es. Multip le languag e versions of a dial og can be exported; also, entr ies for on e language ’s set of dialogs ca n be swapp ed with en tries for another la nguage’s s et of dial ogs.
	6103	KIDS allow s you to e xport entr ies your s oftware ap plication maintains in the DIA LOG file ( #.84). Sim ply select which DIA LOG entrie s you want to includ e in your software a pplication , as you w ould for a ny other s oftware ap plication component, and choos e an insta llation ac tion for e ach item ( the defaul t is SEND TO SITE, t he other p ermissible choice is DELETE AT SITE).
	6104	REF: For m ore inform ation on u sing the D IALOG file (#.84), s ee the VA FileMan De veloper’s Guide.
	6105	Edit a Bui ld: Forms
	6106	You do not need to s elect whic h blocks t o send whe n you send VA FileMa n ScreenMa n forms. Y ou only ne ed to sele ct the for m; KIDS se nds all bl ocks assoc iated with a form on ce you hav e chosen t he form.
	6107	Edit a Bui ld: Templa tes
	6108	When you s elect prin t, sort, o r input te mplates, K IDS append s the file number to the name of the tem plate. Thi s ensures that a uni que entry exists for each temp late (sinc e two temp lates of t he same na me could e xist for t wo differe nt files).
	6109	Figure 58: KIDS—Sele cting temp lates
	6110	Edi t a Build PAGE 2 OF 5
	6111	Name: ZXG DEMO 1.0 TYPE: SINGLE PAC KAGE
	6112	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	6113	BUI LD COMPONE NTS
	6114	┌───────── ────────── ──────── P RINT TEMPL ATE ───── ────────── ────────── ───────┐
	6115	│ │
	6116	│ +XUSER L IST FIL E #200 SEND TO SITE │
	6117	│ XUSERIN Q FILE #200 SEND TO SITE │
	6118	│ XUSERVE R DISPLAY FILE #1 9.081 SEND TO SITE │
	6119	│ XUSERVE R HEADER FILE #19 .081 SEND TO SITE │
	6120	│ XUUFAA FILE #3 .05 SEND TO SITE │
	6121	│ XUUFAAH FILE # 3.05 SEND TO SITE │
	6122	│ XUUSERO PTH FIL E #19.081 SEND TO SITE │
	6123	│ XUUSERO PTP FIL E #19.081 SEND TO SITE │
	6124	│ │
	6125	│ │
	6126	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ───────┘
	6127	__________ __________ __________ __________ __________ __________ __________ _________
	6128
	6129
	6130	COMMAND: Pre ss <PF1>H for help Insert
	6131
	6132	Transporti ng a Distr ibution
	6133	Once you h ave create d a build entry and added all of the fil es and com ponents yo u want to export, yo u are read y to expor t your sof tware appl ication. K IDS uses a transport global as the mecha nism to mo ve data. I NIT routin es are no longer the transport mechanism (which re moves the old restri ctions on the amount of data y ou can exp ort). Tran sport glob als can th en be writ ten to dis tributions , which ar e HFS file s. Use the TRANSPORT option to generate transport globals an d create d istributio ns.
	6134	Depending on how you answer th e question s in this option, th e transpor t globals this optio n generate s can be s tored in:
	6135	A distribu tion, whic h is then ready to e xport as a Host file .
	6136	A PackMan message (t o be sent over the n etwork).
	6137	The ^XTMP global on your local system.
	6138	If you cho ose to tra nsport the distribut ion via a Host file enter HF a fter the “ Transport through (H F)Host Fil e or (PM)P ackMan:” p rompt and enter a Ho st file na me after t he “Enter a Host Fil e” prompt. The optio n creates transport globals an d puts the m in the d istributio n (HFS fil e) that yo u specify.
	6139	Figure 59: KIDS—Tran sport a Di stribution option: C reating a distributi on sample user dialo gue
	6140	Select Edi ts and Dis tribution Option: TR ANSPORT A DISTRIBUTI ON
	6141
	6142	Enter the Package Na mes to be transporte d. The ord er in whic h
	6143	they are e ntered wil l be the o rder in wh ich they a re install ed.
	6144
	6145
	6146	First Pack age Name: ZXG DEMO 1 .0
	6147	Another Pa ckage Name : ZXG TEST 1.0
	6148	Another Pa ckage Name : <Enter>
	6149
	6150	ORDER PA CKAGE
	6151	1 ZXG DEMO 1.0
	6152	2 ZXG TEST 1.0
	6153
	6154
	6155	OK to cont inue? NO// YES
	6156	Transport through (H F)Host Fil e or (PM)P ackMan: HF <Enter> H ost File
	6157
	6158	Enter a Ho st File: Z XG_EXPT.DA T
	6159	Header Com ment: EXPO RT OF ZXG PACKAGE
	6160
	6161
	6162	ZXG D EMO 1.0...
	6163	ZXG T EST 1.0...
	6164
	6165	Package Tr ansported Successful ly
	6166
	6167	Select Edi ts and Dis tribution Option:
	6168
	6169	If you do not enter a Host fil e name, KI DS creates the trans port globa ls and sto res them i n your loc al ^XTMP g lobal, but does not WRITE them to a dist ribution f ile.
	6170	If you hav e previous ly created a transpo rt global for this s oftware ap plication in the ^XT MP global and it sti ll exists, KIDS asks you if yo u want to use what w as already generated or if you want to r e-generate the trans port globa ls instead .
	6171	If you wan t the dist ribution s ent via a PackMan me ssage ente r PM after the “Tran sport thro ugh (HF)Ho st File or (PM)PackM an:” promp t. You can only send one trans port globa l per Pack Man messag e, however .
	6172	Figure 60: KIDS—Tran sport a Di stribution option: S ending via network ( PackMan me ssage) sam ple user d ialogue
	6173	Select Edi ts and Dis tribution Option: TR ANSPORT A DISTRIBUTI ON
	6174
	6175	Enter the Package Na mes to be transporte d. The ord er in whic h
	6176	they are e ntered wil l be the o rder in wh ich they a re install ed.
	6177
	6178	First Pack age Name: TEST 1.1
	6179	Another Pa ckage Name : <Enter>
	6180
	6181	ORDER PA CKAGE
	6182	1 TES T 1.1
	6183
	6184	OK to cont inue? NO// YES
	6185	Transport through (H F)Host Fil e or (PM)P ackMan: PM <Enter> PackMan
	6186
	6187	TEST 1.1...
	6188	No Package File Link
	6189	Subject: T EST
	6190	Please ent er descrip tion of Pa ckman Mess age
	6191
	6192	TEST
	6193
	6194	Created b y XUUSER,F IVE at KER NEL.ISC-SF . D O MAIN (KIDS) on MONDAY, 10 /07/96 at 15:21
	6195	Do you wis h to secur e this mes sage? No// ?
	6196
	6197	If you ans wer yes, t his messag e will be secured to insure th at
	6198	what you s end is wha t is actua lly receiv ed.
	6199	Do you wis h to secur e this mes sage? No// Y <Enter> (Yes)
	6200	Enter the scramble h int: THIS IS A HINT
	6201	Enter scra mble passw ord:
	6202
	6203	The passwo rd entered is not ec hoed back.
	6204	The passwo rd entered is not ec hoed back.
	6205	Securing t he message , now. Th is may tak e a while !!!
	6206
	6207	Send mail to: XUUSER ,FIVE Last used MailMan: 0 4 Oct 96 1 5:28
	6208	Select b asket to s end to: IN // <Enter>
	6209	And send t o: <Enter>
	6210
	6211	When to Tr ansport Mo re than On e Transpor t Global i n a Distri bution
	6212	If several software applicatio ns are unr elated, th ey should be sent as separate distributi ons. This gives the installing site opti mum flexib ility to d ecide when to do eac h installa tion.
	6213	If a group of softwa re applica tions is t o be insta lled toget her, howev er, and if there are dependenc ies betwee n the soft ware appli cations, s ending the software applicatio ns togethe r in one d istributio n can give you more control ov er how the group of software a pplication s is insta lled. If i n some cas es only so ftware app lications A and B sh ould be in stalled, a nd in othe r situatio ns only so ftware app lications A and C sh ould be in stalled, a nd you can do the de terminatio n yourself (in each software a pplication ’s environ ment check routine), sending t he group o f software applicati ons in a s ingle dist ribution l ets you co ntrol whic h software applicati ons in the distribut ion actual ly are ins talled.
	6214	When you a re using P ackMan mes sages to s end your s oftware ap plication (rather th an using a distribut ion), you are limite d to sendi ng only on e transpor t global p er PackMan message.
	6215	Multi-Pack age Builds
	6216	Multi-Pack age builds contain a list of o ther build s and list s their in stallation order. A Multi-Pack age build transports this list of builds (template or meta-b uild).
	6217	Figure 61: KIDS—Mult i-package builds sam ple
	6218	Edi t a Build PAGE 1 OF 5
	6219	Name: TEST 3.0 T YPE: MULTI -PACKAGE
	6220	---------- ---------- ---------- ---------- ---------- ---------- ---------- ------
	6221
	6222	Name: TES T 3.0
	6223
	6224	D ate Distri buted: OCT 9,2004
	6225
	6226	Descri ption:
	6227
	6228
	6229	Install Or der Packages or Patches
	6230	1 TEST 1.0
	6231	2 TEST 1.1
	6232
	6233
	6234	__________ __________ __________ __________ __________ __________ __________ __________ _
	6235
	6236
	6237	COMMAND: Pre ss <PF1>H for help Insert
	6238
	6239	Exporting Globals wi th KIDS
	6240	KIDS in Ke rnel 8.0 s upports th e installa tion of gl obal distr ibutions ( distributi ons that e xport glob als). KIDS supports the creati on of glob al distrib utions by developers . Any numb er of glob als can be included in a build . You are given the opportunit y to run a n environm ent check before ins talling th e global a nd post-in stall rout ines after installin g the glob als. You a lso are gi ven the ch oice of KI LLing glob als prior to install ing new gl obals at a site. If you answer NO to thi s question , the glob al is merg ed with an y previous ly install ed global at the sit e.
	6241	REF: For m ore inform ation on g lobal dist ributions, see the “ KIDS: Syst em Managem ent—Instal lations” s ection in the Kernel Systems M anagement Guide.
	6242	Figure 62: KIDS—Expo rting glob al distrib utions sam ple
	6243	Edi t a Build PAGE 1 OF 5
	6244	Name: TEST 5.0 TYPE: GLOB AL PACKAGE
	6245	---------- ---------- ---------- ---------- ---------- ---------- ---------- ------
	6246
	6247	N ame: TEST 5.0
	6248
	6249	Dat e Distribu ted: OCT 9 ,2004
	6250
	6251	Descript ion:
	6252
	6253	Environme nt Check R tn.: Post-In stall Rtn. :
	6254
	6255	Globals Kill Gl obal Befor e Install?
	6256	TMP(100 ) NO
	6257
	6258
	6259	__________ __________ __________ __________ __________ __________ __________ _________
	6260
	6261
	6262	COMMAND: Pre ss <PF1>H for help Insert
	6263
	6264	Creating T ransport G lobals tha t Install Efficientl y
	6265	There are some choic es you can make when designing your buil d entries, to make y our transp ort global s install efficientl y at the r eceiving s ite. In pa rticular, you can im prove the efficiency of export ing data e ntries usi ng KIDS:
	6266	When expor ting data, you can u se the ADD IF NEW op tion to on ly add ent ries if th e file did not exist prior to the instal lation. Da ta is only added if the file i s created by the ins tallation. You can u se this op tion to av oid re-exp orting dat a for stat ic files.
	6267	When expor ting data, send only the data you need t o (KIDS no longer fo rces you t o send all data in a file when you only need to se nd some of the data) . You can select a s ubset of d ata to sen d by using a screen, a search template, or both a screen and a search template.
	6268	When expor ting data, resolve p ointers on ly if nece ssary, bec ause resol ving point ers adds s ignificant overhead to the pro cess of lo ading data entries.

	6269	Advanced B uild Techn iques
	6270	The previo us section s in this section in troduced K IDS from t he develop er’s persp ective, de scribing t he basics of how to create bui ld entries and how t o transpor t distribu tions. Thi s section describes advanced b uild techn iques that developer s can use when creat ing builds . The foll owing subj ects are c overed:
	6271	Environmen t Check Ro utine
	6272	PRE-TRANSP ORTATION R OUTINE fie ld (#900)
	6273	Pre- and P ost-Instal l Routines : Special Features
	6274	Edit a Bui ld—Screen 4
	6275	How to Ask Installat ion Questi ons
	6276	Using Chec kpoints (P re- and Po st-Install Routines)
	6277	Required B uilds
	6278	Package Fi le Link
	6279	Track Pack age Nation ally
	6280	Alpha/Beta Tracking
	6281	Environmen t Check Ro utine
	6282	KIDS, like DIFROM, l ets you sp ecify an e nvironment check rou tine. Typi cally, the environme nt check r outine loo ks at the installing system an d determin es whether it’s appr opriate to install t he softwar e applicat ion, based on condit ions on th e installi ng site’s current sy stem or en vironment.
	6283	You are no t required to specif y an envir onment che ck in orde r for your software applicatio n to be in stalled. I f, however , you have some spec ial checks that you want to ma ke to deci de whether it is app ropriate t o go ahead with the installati on, the en vironment check rout ine is the place to do it.
	6284	KIDS lets you specif y the name of the en vironment check rout ine in scr een one of EDIT A BU ILD (Figur e 67). Any routine t hat is spe cified is automatica lly sent b y KIDS. Yo u do not h ave to lis t the rout ine in the Build Com ponents se ction (Fig ure 56).
	6285	Self-Conta ined Routi ne
	6286	The enviro nment chec k routine itself mus t be a sin gle, self- contained routine, b ecause it is the onl y routine from your build that is loaded on the in stalling s ite’s syst em at the time it is executed by KIDS. B ased on wh at you fin d out abou t the inst alling sys tem during the envir onment che ck, you ca n tell KID S to conti nue instal ling the s oftware ap plication, abort ins talling th e software applicati on, or abo rt install ing all so ftware app lications (transport globals) in the dis tribution.
	6287	Although o utput duri ng the pre -install a nd post-in stall shou ld be done with the MES^XPDUTL (): Output a Message and BMES^ XPDUTL(): Output a M essage wit h Blank Li ne APIs, d uring the environmen t check ro utine you should use direct RE ADs and WR ITEs.
	6288	Environmen t Check is Run Twice
	6289	KIDS runs the enviro nment chec k routine twice. It runs the e nvironment check rou tine first when the installer loads the transport global fro m the dist ribution ( with the L oad a Dist ribution o ption).
	6290	KIDS runs the enviro nment chec k a second time when the user runs the I nstall Pac kage(s) op tion [XPD INSTALL BU ILD] to in stall the software a pplication s in the l oaded dist ribution.
	6291	The KIDS k ey variabl e XPDENV i ndicates i n which ph ase (load or install ) the envi ronment ch eck is run ning.
	6292	REF: For m ore inform ation on X PDENV, see the “Key Variables during Env ironment C heck” sect ion.
	6293	Key Variab les during Environme nt Check

	6294	Table 15: KIDS—Key v ariables d uring the environmen t check
	6295	Variable
	6296	Descriptio n
	6297	XPDNM
	6298	The KIDS k ey variabl e XPDNM is available during th e environm ent check, as well a s during t he pre- an d post-ins tall phase s of a KID S installa tion. XPDN M is set t o the name of the tr ansport gl obal curre ntly being installed . It is in the forma t of the . 01 field o f the soft ware appli cation’s B UILD file (#9.6) ent ry, which is softwar e applicat ion name, concatenat ed with a space, con catenated with versi on number.
	6299	XPDNM(“TST ”)
	6300	Released w ith Kernel patch XU* 8.0*559, t he XPDNM(“ TST”) vari able is av ailable du ring the p re- and po st-install and envir onment che ck phases of a KIDS installati on. XPDNM( “TST”) is set to one of the fo llowing va lues:
	6301	Test Numbe r—If build is a patc h and the National P atch Modul e (NPM) cr eated a te st number.
	6302	Null.
	6303	XPDNM(“SEQ ”)
	6304	Released w ith Kernel patch XU* 8.0*559, t he XPDNM(“ SEQ”) vari able is av ailable du ring the p re- and po st-install and envir onment che ck phases of a KIDS installati on. XPDNM( “SEQ”) is set to one of the fo llowing va lues:
	6305	Sequence N umber—If b uild is a patch and the Nation al Patch M odule (NPM ) created a sequence number.
	6306	Null.
	6307	XPDENV
	6308	The KIDS k ey variabl e XPDENV i s availabl e during t he environ ment check only. It can have t he followi ng values:
	6309	1—The envi ronment ch eck is bei ng run by the KIDS I nstall Pac kage(s) op tion.
	6310	0—The envi ronment ch eck is bei ng run by the KIDS L oad a Dist ribution o ption.
	6311	You can us e XPDENV i f, for exa mple, ther e is a che ck that is valid to perform at install t ime, but n ot at load time.
	6312	DIFROM
	6313	For the pu rpose of b ackward co mpatibilit y, the var iable DIFR OM is avai lable duri ng the env ironment c heck, as w ell as dur ing the pr e- and pos t-install phases of a KIDS ins tallation. DIFROM is set to th e version number of the incomi ng softwar e applicat ion.
	6314
	6315	Package Ve rsion vs. Installing Version
	6316	KIDS provi des severa l function s that you can use d uring the environmen t check to compare v ersion num bers of th e current software a pplication at the si te to the incoming t ransport g lobal:
	6317	$$VER^XPDU TL
	6318	$$VERSION^ XPDUTL
	6319	REF: For m ore on the se APIs, s ee the “Ap plication Programmin g Interfac e (API)” s ection in this secti on.
	6320	Telling KI DS to Skip Installin g or Delet e a Routin e
	6321	During the environme nt check, you can te ll KIDS to skip inst alling any routine, and change a routine ’s install ation stat us to DELE TE AT SITE .
	6322	For exampl e, suppose you have one versio n of a rou tine for G T.M sites and one ve rsion for Caché site s. Based o n the type of system your envi ronment ch eck finds, you can u se the $$R TNUP^XPDUT L(): Updat e Routine Action fun ction to t ell KIDS w hich routi nes to ski p installi ng.
	6323	REF: For m ore inform ation on d eleting en vironment check rout ines, see the “Key P arameters during Pre - and Post -Install R outines” s ection in this secti on.
	6324	Verifying Patch Inst allation
	6325	During the environme nt check, you can te ll KIDS to verify th at a parti cular patc h has been installed on a syst em prior t o the inst allation o f your sof tware appl ication.
	6326	For exampl e, if your software applicatio n is depen dent on a particular patch bei ng install ed, you ca n use the $$PATCH^XP DUTL(): Ve rify Patch Installat ion functi on to have KIDS aler t the user that a re quired pat ch is not installed on their s ystem.
	6327	Aborting I nstallatio ns During the Enviro nment Chec k
	6328	In the env ironment c heck, you can decide whether a n installa tion shoul d continue or stop, or whether the insta llation of all trans port globa ls in the distributi on should be aborted .
	6329	When you a bort the i nstallatio n of a tra nsport glo bal by set ting XPDQU IT or XPDA BORT, KIDS outputs a message t o the effe ct that a particular transport global in the insta llation is being abo rted. You should als o issue yo ur own mes sage when aborting a n installa tion, howe ver, to gi ve the sit e some dia gnostic in formation as to why you have c hosen to a bort the i nstall.
	6330	Table 16 l ists ways you can as k KIDS to continue o r abort an installat ion, based on the co nclusions of your en vironment check rout ine:
	6331	Table 16: KIDS—Actio ns based o n environm ent check conclusion s
	6332	KIDS Desir ed Action( Based on E nvironment Check Con clusions)
	6333	How to Tel l KIDS to Take Actio n
	6334	OK to inst all this t ransport g lobal.
	6335	(Take no a ction)
	6336	Do not ins tall this transport global and KILL it f rom ^XTMP.
	6337	>S XPDQUIT =1
	6338	Do not ins tall this transport global but leave it in ^XTMP.
	6339	>S XPDQUIT =2
	6340	Abort anot her transp ort global named pkg _name in d istributio n and KILL it from ^ XTMP.
	6341	>S XPDQUIT (pkg_name) =1
	6342	Abort anot her transp ort global named pkg _name in d istributio n but leav e it in ^X TMP.
	6343	>S XPDQUIT (pkg_name) =2
	6344	Abort all transport globals in distribut ion and KI LL them fr om ^XTMP.
	6345	>S XPDABOR T=1
	6346	Abort all transport globals in distribut ion but le ave them i n ^XTMP.
	6347	>S XPDABOR T=2
	6348
	6349	NOTE: It i s recommen ded that y ou use XPD QUIT when you have a distribut ion that c ontains mu ltiple bui lds and yo u only wan t to selec tively ins tall a por tion of it . Use the XPDABORT t o abort th e entire i nstallatio n of a dis tribution.
	6350	Controllin g the Queu ing of the Install P rompt
	6351	By default , KIDS all ows the in staller to run in th e future. It does th is by allo wing the i nstaller t o enter “Q ” at the d evice prom pt. If the XPDNOQUE variable i s set to 1 , then the installer sees the following prompt and not be al lowed to e nter “Q”:
	6352	Figure 63: KIDS—Dial ogue when the XPDNOQ UE variabl e is set t o disable queuing
	6353	Enter the Device you want to p rint the I nstall mes sages.
	6354	Enter a ‘^ ’ to abort the insta ll.
	6355
	6356	DEVICE: HO ME//
	6357
	6358	Controllin g the Disa ble Option s/Protocol s Prompt
	6359	By default , KIDS ask s the foll owing ques tion durin g KIDS ins tallations :
	6360	Figure 64: KIDS—”DIS ABLE” defa ult prompt during in stallation s
	6361	Want to DI SABLE Sche duled Opti ons, Optio ns, and Pr otocols? Y ES//
	6362
	6363	You can co ntrol the way this q uestion is asked by defining t he array X PDDIQ(“XPZ 1”) during the envir onment che ck. The en vironment check runs once duri ng the ins tallation and prompt s the user if it sho uld run du ring the l oad. Setti ng this ar ray only h as an effe ct during the instal lation. Th erefore, y ou may wan t to defin e the arra y only whe n XPDENV=1 . You can use this a rray as fo llows (eac h node is optional):
	6364	Table 17: KIDS—Insta llation: X PDDIQ arra y sample
	6365	Array Node
	6366	Descriptio n
	6367	XPDDIQ(“XP Z1”)
	6368	(optional) Set to ze ro (0) to force answ er to NO o r set to 1 to force answer to YES. When this node is set, th e site is not asked the questi on.
	6369	XPDDIQ(“XP Z1”,“A”)
	6370	(optional) Replace t he default question prompt wit h the valu e of this node.
	6371	XPDDIQ(“XP Z1”,“B”)
	6372	(optional) Set to ne w default answer in external f orm (YES o r NO).
	6373
	6374	Controllin g the Move Routines to Other C PUs Prompt
	6375	By default , KIDS ask s the foll owing ques tion durin g KIDS ins tallations :
	6376	Figure 65: KIDS—”MOV E routines ” default prompt dur ing instal lations
	6377	Want to MO VE routine s to other CPUs? NO/ /
	6378
	6379	You can co ntrol the way this q uestion is asked by defining t he array X PDDIQ(“XPZ 2”) during the envir onment che ck. The en vironment check runs twice (on ce during load and o nce during installat ion), but setting th is array o nly has an effect du ring the i nstallatio n. Therefo re, you ma y want to define the array onl y when XPD ENV=1. You can use t his array as follows (each nod e is optio nal):
	6380	Table 18: KIDS—Envir onment Che ck—XPDDIQ array samp le
	6381	Array Node
	6382	Descriptio n
	6383	XPDDIQ(“XP Z2”)
	6384	(optional) Set to ze ro (0) to force answ er to NO, or set to 1 to force answer to YES. When this node is set, t he questio n is not a sked.
	6385	XPDDIQ(“XP Z2”,“A”)
	6386	(optional) Replace t he default question prompt wit h the valu e of this node.
	6387	XPDDIQ(“XP Z2”,“B”)
	6388	(optional) Set to ne w default answer in external f orm (YES o r NO).
	6389
	6390	Figure 66: KIDS—Envi ronment Ch eck routin e sample
	6391	ZZUSER1 ;SFISC/R WF - CHECK TO SEE IF OK TO LOA D ; 8 Sep 94 10:39
	6392	;;8.0 T13;KERNEL ;;Aug 01, 1994
	6393	N Y
	6394	I $S( $D(DUZ)[0: 1,$D(DUZ(0 ))[0:1,’DU Z:1,1:0) W !!,*7,“>> DUZ and D UZ(0) must be define d as an ac tive user to initial ize.” S XP DQUIT=2
	6395	I $D( ^DD(200,0) )[0,XPDNM’ [“VIRGIN I NSTALL” W !!,“You ne ed to inst all the KE RNEL - VIR GIN INSTAL L 8.0 pack age, inste ad of this package!! ” G ABRT
	6396	;chec k for Tool kit 7.3
	6397	I $$V ERSION^XPD UTL(“XT”)< 7.3 W !!,“ You need T oolkit 7.3 installed !” G ABRT
	6398	;
	6399	W !,“ I’m checki ng to see if it is O K to insta ll KERNEL v”,$P($T(+ 2),“;”,3), “ in this account.”, !
	6400	W !!, “Checking the %ZOSV routine” D GETENV^%Z OSV
	6401	I $P( Y,“^”,4)=“ ” W !,“The %ZOSV rou tine isn’t current.” ,!,“Check the second line of t he routine , or your routine ma p table.” S XPDQUIT= 2
	6402	;must have Kern el 7.1
	6403	S Y=$ $VERSION^X PDUTL(“XU” ) G:Y<7.1 OLD
	6404	;Test Access to % globals , only che ck during install
	6405	D:$G( XPDENV) GB LOK
	6406	I ‘$G (XPDQUIT) W !!,“Ever ything loo ks OK, Let s continue .”,!
	6407	Q
	6408	;
	6409	OLD W !!, *7,“It loo ks like yo u currentl y have ver sion “,Y,” of KERNEL installed .”
	6410	W !,* 7,“You mus t first in stall KERN EL v7.1 be fore this version ca n be insta lled.”,!
	6411	;abor t install, delete tr ansport gl obal
	6412	ABRT S XPD QUIT=1
	6413	Q
	6414	;
	6415	GBLOK ;Check t o see if w e have WRI TE access to needed globals.
	6416	W !,“ Now to che ck protect ion on GLO BALS.”,!,“ If you get an ERROR, you need to add WRI TE access to that gl obal.”,!
	6417	F Y=“ ^%ZIS”,“^% ZISL”,“^%Z TER”,“^%ZU A” W !,“Ch ecking “,Y S @(Y_”=$ G(“_Y_”)”)
	6418	Q
	6419
	6420	PRE-TRANSP ORTATION R OUTINE fie ld (#900)
	6421	The PRE-TR ANSPORTATI ON ROUTINE field (#9 00) in the BUILD fil e (#9.6) c ontains a [TAG^]ROUT INE that i s run duri ng the tra nsportatio n process for the Bu ild. This allows dev elopers to populate the transp ort global using the XPDGREF v ariable.
	6422	Developers can put i nformation in the KI DS Transpo rt Global, which can be used b y the Pre- install, E nvironment Check, an d/or Post- install ro utines. KI DS runs th e [TAG^]RO UTINE in t he field P RE-TRANSPO RTATION RO UTINE duri ng the tra nsport pro cess. This routine c an use the XPDGREF v ariable to set nodes in the tr ansport gl obal. For example, e nter the f ollowing a t the prog rammer pro mpt:
	6423	>S @XPDGRE F@(“My Nam espace”,1) =“Informat ion I need during in stall”
	6424	During the install p rocess, in the Pre-i nstall, En vironment Check, and /or Post-i nstall rou tines, the developer can retri eve the da ta by usin g the same variable, XPDGREF. Since thes e nodes ar e part of the transp ort global , they are removed w hen the in stall is c ompleted.
	6425	Figure 67: KIDS—PRE- TRANSPORTA TION ROUTI NE field s ample
	6426	Edi t a Build PAGE 1 O F 4
	6427	Name: TEST 4.0 TYPE: S INGLE PACK AGE
	6428	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	6429
	6430	Name: TE ST 4.0
	6431
	6432	Date Distr ibuted: OC T 9,2004
	6433
	6434	Descr iption:
	6435
	6436	Environme nt Check R outine:
	6437
	6438	Pre -Install R outine:
	6439
	6440	Post -Install R outine:
	6441
	6442	Pre-Transp ortation R outine: TA G^ROUTINE
	6443	__________ __________ __________ __________ __________ __________ __________ __________ ___
	6444
	6445
	6446	COMMAND Press P F1H for he lp Inse rt
	6447
	6448	Pre- and P ost-Instal l Routines : Special Features
	6449	KIDS, like DIFROM, l ets you sp ecify pre- install an d post-ins tall routi nes. Typic ally, the pre- and p ost-instal l routines are used to perform pre-insta ll and pos t-install conversion s. This se ction desc ribes how to use pre - and post -install r outines wi th KIDS in stallation s.
	6450	Pre- and p ost-routin es are opt ional; you are not r equired to specify t hem in ord er for you r software applicati on to be i nstalled. If, howeve r, you hav e some spe cial actio ns you wan t to take, either be fore or af ter your i nstallatio n, the pre - and post -install r outines ar e the plac es to do i t.
	6451	KIDS lets you specif y the name s for pre- and post- install ro utines in screen one of EDIT A BUILD (Fi gure 67). Any routin e that is specified is automat ically sen t by KIDS. You do no t have to list the r outine in the Build Components section ( Figure 56) .
	6452	Two functi ons can be called du ring the i nstall pro cess to di sable or e nable an o ption or p rotocol:
	6453	$$OPTDE^XP DUTL(): Di sable/Enab le an Opti on
	6454	$$PRODE^XP DUTL(): Di sable/Enab le a Proto col
	6455	Do not set up variab les during the pre-i nstall for use durin g the inst allation o r the post -install, because th ese variab les are lo st if the installati on aborts midway thr ough and t hen is res tarted by the site u sing the r estart opt ion.
	6456	You can re ference an y routine exported i n your bui ld, since all routin es with a SEND TO SI TE action are instal led by the time the pre- and p ost-instal l routines run.
	6457	Aborting a n Installa tion Durin g the Pre- Install Ro utine
	6458	You can ab ort an ins tallation during the pre-insta ll routine by settin g the XPDA BORT varia ble to 1 a nd quittin g. This is exactly a s if the i nstalling site press ed <CTRL>C , in the s ense that no cleanup is done; options ar e left dis abled. KID S prints o ne message to the ef fect that the instal l aborted in the pre -install p rogram. If you abort an instal lation in this manne r, you nee d to tell the site w hat to do to either re-start t he install ation or c lean up th e system f rom the st ate it was left in.
	6459	Setting a File’s Pac kage Revis ion Data N ode (Post- Install)
	6460	A new Pack age Revisi on Data no de can now be update d during t he post-in stall. Thi s node is located in ^DD(filen umber,0,“V RRV”). It is defined by the de veloper wh o distribu tes the so ftware app lication a nd may con tain patch or revisi on informa tion regar ding the f ile. $$GET 1^DID can be used to retrieve the conten t of the n ode and PR D^DILFD up dates the node.
	6461	REF: For m ore inform ation, see the VA Fi leMan Deve loper’s Gu ide.
	6462	Key Parame ters durin g Pre- and Post-Inst all Routin es

	6463	Table 19: KIDS—Key p arameters during the pre- and post-insta ll routine s
	6464	Parameter
	6465	Descriptio n
	6466	XPD NO_EPP _DELETE
	6467	If this pa rameter is set to 1, KIDS does not delet e any envi ronment ch eck Pre an d Post rou tines, reg ardless if the Envir onment Che ck routine is marked as “DELET E AT SITE. ” By defau lt, this p arameter i s set to 1 (do not d elete), so support p ersonnel a re able to look at t hose routi nes for tr oubleshoot ing purpos es.
	6468
	6469	Key Variab les during Pre- and Post-Insta ll Routine s

	6470	Table 20: KIDS—Key v ariables d uring the pre- and p ost-instal l routines
	6471	Variable
	6472	Descriptio n
	6473	XPDNM
	6474	The XPDNM variable i s availabl e during t he pre- an d post-ins tall and e nvironment check pha ses of a K IDS instal lation. XP DNM is set to the na me of the build curr ently bein g installe d. It is i n the form at of the .01 field of the sof tware appl ication’s BUILD file (#9.6) en try, which is softwa re applica tion name, concatena ted with a space, co ncatenated with vers ion number .
	6475	XPDNM(“TST ”)
	6476	Released w ith Kernel patch XU* 8.0*559, t he XPDNM(“ TST”) vari able is av ailable du ring the p re- and po st-install and envir onment che ck phases of a KIDS installati on. XPDNM( “TST”) is set to one of the fo llowing va lues:
	6477	Test Numbe r—If build is a patc h and the National P atch Modul e (NPM) cr eated a te st number.
	6478	Null.
	6479	XPDNM(“SEQ ”)
	6480	Released w ith Kernel patch XU* 8.0*559, t he XPDNM(“ SEQ”) vari able is av ailable du ring the p re- and po st-install and envir onment che ck phases of a KIDS installati on. XPDNM( “SEQ”) is set to one of the fo llowing va lues:
	6481	Sequence N umber—If b uild is a patch and the Nation al Patch M odule (NPM ) created a sequence number.
	6482	Null.
	6483	DIFROM
	6484	For the pu rpose of b ackward co mpatibilit y, the DIF ROM variab le is avai lable duri ng the pre - and post -install ( as well as environme nt check) phases of a KIDS ins tallation. DIFROM is set to th e version number of the incomi ng softwar e applicat ion.
	6485	ZTQUEUED
	6486	If the ZTQ UEUED vari able is pr esent, you know that you are r unning as a queued i nstallatio n. If ZTQU EUED is no t present, you know that the i nstaller c hose to ru n the inst allation d irectly in stead of q ueuing it.
	6487
	6488	NEW the DI FROM Varia ble When C alling Mai lMan
	6489	You are fr ee to use the MailMa n API to s end mail m essages du ring pre- and post-i nstall rou tines (pro vided Mail Man exists on the ta rget syste m). Make s ure that y ou NEW the DIFROM va riable bef ore callin g any of t he MailMan APIs, how ever. Mail Man APIs c an termina te prematu rely if th e DIFROM v ariable is present b ecause the DIFROM va riable has a special meaning w ithin Mail Man.
	6490	Update the Status Ba r During P re- and Po st-Install Routines
	6491	During the installat ion, if th e device s elected fo r output i s a VT100- compatible (or highe r) termina l, KIDS di splays the installat ion output in a virt ual window on the te rminal. Be low the vi rtual wind ow, a prog ress bar g raphically illustrat es the per centage co mplete tha t the curr ent part o f the inst allation h as reached . KIDS res ets the st atus bar p rior to th e Pre- and Post-inst all routin es.
	6492	REF: For m ore inform ation on t he status (progress) bar, see the “Insta llation Pr ogress” se ction in t he “KIDS S ystems Man agement In stallation s” section in the Ke rnel Syste ms Managem ent Guide.
	6493	You can pr ovide a si milar stat us bar for users in the Pre- a nd Post-In stall by d oing the f ollowing:
	6494	SET XPDIDT OT=total n umber of i tems.
	6495	DO UPDATE^ XPDID(curr ent number of items) . This mov es the sta tus bar.
	6496	For exampl e, if you were conve rting 100 records an d want to update the user ever y time you have comp leted 10% of the rec ords you w ould enter the follo wing at th e programm er prompt:
	6497
	6498	>SET XPDID TOT=100
	6499	>F%=1:1:10 0 D CONVER T I’(%#10) D UPDATE^ XPDID(%)
	6500	If you wis h to displ ay a statu s bar at v arious int ervals thr oughout yo ur Pre or Post-insta ll routine s, you sho uld reset the status bar. To r eset the s tatus bar enter the following at the pro grammer pr ompt:
	6501
	6502	>SET XPDID TOT=0
	6503	>D UPDATE^ XPDID(0)
	6504
	6505	Edit a Bui ld—Screen 4
	6506	Screen fou r of the E DIT A BUIL D option i s where yo u can set up the ins tall quest ions, any required b uilds, PAC KAGE file (#9.4) lin ks, and tr acking sof tware appl ication in formation for a buil d.
	6507	Figure 68: KIDS—Scre en 4 of Ed it a Build sample
	6508	Edi t a Build PAGE 4 O F 5
	6509	Name: TEST 1.0 TYP E: SINGLE PACKAGE
	6510	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------- ---
	6511	Insta ll Questio ns
	6512
	6513
	6514
	6515
	6516	Requi red Builds
	6517
	6518
	6519	Pack age File L ink...: TE ST
	6520
	6521	Track Pa ckage Nati onally: NO
	6522	__________ __________ __________ __________ __________ __________ __________ __________ ___
	6523
	6524
	6525	COMMAND: Press <P F1>H for h elp Ins ert
	6526
	6527	How to Ask Installat ion Questi ons
	6528	You are no t required to ask an y installa tion quest ions in or der for yo ur softwar e applicat ion to be installed. If, howev er, you ha ve some sp ecial acti ons that y ou can tak e in your pre-instal l and post -install p rocesses, and these special ac tions depe nd on info rmation yo u need to get from y our instal ler, then you need a way to as k these qu estions.
	6529	Screen fou r of the E DIT A BUIL D option i s where yo u can set up the ins tall quest ions for a build.
	6530	To ask que stions, yo u need to supply KID S with the proper DI R input va lues for e ach questi on. Then, KIDS uses the DIR ut ility to a sk install ation ques tions when performin g installa tions. The DIR input values yo u can supp ly for eac h question are:
	6531	Table 21: KIDS—DIR i nput value s for KIDS install q uestions
	6532	DIR Input Value
	6533	Descriptio n
	6534	DIR(0)
	6535	Question f ormat.
	6536	DIR(A)
	6537	Question p rompt.
	6538	DIR(A,#)
	6539	Additional message b efore ques tion promp t.
	6540	DIR(B)
	6541	Default an swer.
	6542	DIR(?)
	6543	Simple hel p string.
	6544	DIR(?,#)
	6545	Additional simple he lp.
	6546	DIR(??)
	6547	Help frame .
	6548	REF: For i nformation on the pu rpose of t hese varia bles, perm issible va lues for t hem, and w hich are r equired ve rsus which are optio nal, see t he VA File Man Develo per’s Guid e.
	6549	Question S ubscripts
	6550	For each q uestion yo u want to ask, the . 01 field o f the ques tion (as s tored by K IDS) is a subscript. The subsc ript must be in one of two for ms:
	6551	Pre-Instal l Question s—PRExxx
	6552	Post-Insta ll Questio ns—POSxxx
	6553	Where “xxx ” in the s ubscript c an be any string up to 27 char acters in length. KI DS asks qu estions wh ose subscr ipt starts with PRE during the pre-insta ll and que stions who se subscri pt starts with POS d uring the post-insta ll.
	6554	The order in which q uestions a re asked d uring the pre- or po st-install s is the s ame as the sorting o rder of th e subscrip t itself. KIDS asks questions with the l owest sort ing subscr ipt first and procee ds to the highest so rting subs cript.
	6555	M Code in Questions
	6556	Besides sp ecifying t he DIR inp ut variabl es, you ca n specify a line of M code tha t is execu ted after the DIR in put variab les have b een set up but prior to the DI R call. Th e purpose of this li ne of M co de is so t hat you ca n modify t he DIR par ameters, i f necessar y, before ^DIR is ac tually cal led.
	6557	The M code must be s tandalone, however; it cannot depend on any routin e in the s oftware ap plication (other tha n the envi ronment ch eck routin e) since n o other ex ported rou tines besi des the en vironment check rout ine are lo aded on th e installi ng system.
	6558	Skipping I nstallatio n Question s
	6559	If you wan t to preve nt a quest ion from b eing asked , you shou ld KILL th e DIR vari able in th e line of M code for that ques tion (exec ute K DIR) .
	6560	Accessing Questions and Answer s
	6561	Once the q uestions h ave been a sked, the results of the quest ions are a vailable ( during pre -install a nd post-in stall only ) in the f ollowing l ocations:
	6562	Pre-Instal l Question s:
	6563	XPDQUES(PR Exxx)=inte rnal form of answer
	6564	XPDQUES(PR Exxx, “A”) =prompt
	6565	XPDQUES(PR Exxx, “B”) =external form of an swer
	6566	Post-Insta ll Questio ns:
	6567	XPDQUES(PO Sxxx)=inte rnal form of answer
	6568	XPDQUES(PO Sxxx, “A”) =prompt
	6569	XPDQUES(PO Sxxx, “B”) =external form of an swer
	6570	The result s of the q uestions f or the pre -install c an only be accessed (in XPDQUE S) during the pre-in stall, and the resul ts of the questions for the po st-install can only be accesse d (in XPDQ UES) durin g the post -install. At all oth er times, XPDQUES is undefined for pre- and post-i nstall que stions.
	6571	Figure 69: KIDS—Pre- install qu estion (se tting up) sample
	6572	Edi t a Build PAGE 4 OF 5
	6573	┌───────── ────────── ────── Ins tall Quest ions ───── ────────── ────────── ────────┐
	6574	│ Name: PRE1 │
	6575	│ │
	6576	│ DIR(0): YA^^ │
	6577	│ │
	6578	│ DIR(A): Do you wa nt to run the pre-in stall conv ersion? │
	6579	│DIR(A,#): │
	6580	│ │
	6581	│ DIR(B): YES │
	6582	│ │
	6583	│ DIR(?): Answer YE S to run t he pre-ins tall conve rsion, NO to skip it . │
	6584	│DIR(?,#): │
	6585	│ DIR(??): │
	6586	│ │
	6587	│ M Code: │
	6588	└───────── ────────── ────────── ────────── ────────── ────────── ────────── ────────┘
	6589	__________ __________ __________ __________ __________ __________ __________ __________ __
	6590
	6591
	6592	COMMAND: Press <PF1 >H for hel p Inser t
	6593
	6594	Figure 70: KIDS—Appe arance of question d uring inst allation
	6595	Do you wan t to run t he pre-ins tall conve rsion? YES // ?
	6596
	6597	Answer YES to run th e pre-inst all conver sion, NO t o skip it. ..
	6598
	6599	Do you wan t to run t he pre-ins tall conve rsion? YES //
	6600
	6601	Where Ques tions Are Asked Duri ng Install ations
	6602	KIDS asks the pre- a nd post-in stall ques tions when a site in itiates an installat ion of the software applicatio n. The ord er of the questions is:
	6603	KIDS runs environmen t check ro utine, if any.
	6604	KIDS asks pre-Instal l question s.
	6605	KIDS asks generic KI DS install ation ques tions.
	6606	KIDS asks post-Insta ll questio ns.
	6607	KIDS asks site to qu eue the in stallation or run it directly.
	6608	Using Chec kpoints (P re- and Po st-Install Routines)
	6609	KIDS allow s the inst alling sit e to resta rt install ations tha t have abo rted. This means tha t your pre -install a nd post-in stall rout ines must be “restar t-aware:” that is, t hey must b e able to run correc tly whethe r it’s the first tim e they’re executed o r whether it is the nth time t hrough.
	6610	KIDS maint ains a set of intern al checkpo ints durin g an insta llation. F or each ph ase of the installat ion (for e xample, co mpletion o f each sof tware appl ication co mponent), it uses a checkpoint to record whether t hat phase of the ins tallation has comple ted yet. I f an insta llation er rors out, checkpoint ing allows the insta llation to be restar ted, not f rom the ve ry beginni ng, but in stead only from the last compl eted check point onwa rd.
	6611	In your pr e- and pos t-install routines, you can us e your own checkpoin ts. If the re is an e rror durin g the pre- or post-i nstall, an d you use checkpoint s, when th e sites re start the installati on, it res umes from the last c ompleted c heckpoint rather tha n running through th e entire p re- or pos t-install again.
	6612	Another ad vantage of using che ckpoints i s that you can recor d timing i nformation for each phase of y our pre- a nd post-in stall rout ines, whic h allows y ou to eval uate the e fficiency of each ph ase you de fine.
	6613	There are two distin ct types o f checkpoi nts you ca n create d uring pre- and post- install ro utines:
	6614	Checkpoint s with cal lbacks
	6615	Checkpoint s without callbacks.
	6616	Checkpoint s with Cal lbacks
	6617	The prefer red method of using checkpoint s is to us e checkpoi nts with c allbacks. When you c reate a ch eckpoint w ith a call back, you give the c heckpoint an API (th e callback routine). That is a ll you hav e to do du ring your pre- or po st-install routine, create a c heckpoint with a cal lback. You do not ha ve to exec ute the ca llback. At the compl etion of t he pre- or post-inst all routin e, KIDS ma nages the created ch eckpoints by calling , running, and compl eting the checkpoint and its c allback ro utine.
	6618	The reason to let KI DS execute checkpoin ts (by cre ating chec kpoints wi th callbac ks) is to ensure tha t the pre- install or post-inst all runs i n the same way wheth er it is t he first i nstallatio n pass, or if the in stallation aborted a nd has bee n restarte d. If the installati on has res tarted, KI DS skips a ny checkpo ints in th e pre-inst all or pos t-install that have completed, and only executes t he callbac ks of chec kpoints th at have no t yet comp leted (and completes them).
	6619	In this sc enario (ch eckpoints with callb ack routin es), your pre-instal l and post -install r outine sho uld consis t only of calls to t he $$NEWCP ^XPDUTL(): Create Ch eckpoint f unction to create ch eckpoints (with call backs). On ce you cre ate all of the check points for each disc rete pre- or post-in stall task , the pre- install or post-inst all should quit.
	6620	Once the p re- or pos t-install routine fi nishes, KI DS execute s each cre ated check point (tha t has a ca llback) in the order created. If it is t he first t ime throug h, each ch eckpoint i s executed . If the i nstallatio n has been restarted , KIDS ski ps any com pleted che ckpoints, and only e xecutes ch eckpoints that have not comple ted.
	6621	The KIDS c heckpoint functions that apply when usin g checkpoi nts with c allbacks a re summari zed below (listed in alphabeti c order):
	6622	Table 22: KIDS—Funct ions using checkpoin ts with ca llbacks
	6623	Function
	6624	Descriptio n
	6625	$$NEWCP^XP DUTL
	6626	Create che ckpoint (u se during pre- or po st-install routine o nly.)
	6627	$$UPCP^XPD UTL
	6628	Update che ckpoint pa rameter (u se within callback r outine.)
	6629	$$CURCP^XP DUTL
	6630	Retrieve c urrent che ckpoint na me (use du ring pre- or post-in stall rout ine). Usef ul when us ing the sa me tag^rou tine for m ultiple ca llbacks; t his is how you deter mine which callback you’re in.
	6631	$$PARCP^XP DUTL
	6632	Retrieve c heckpoint parameter (use withi n callback routine.)
	6633
	6634	Checkpoint Parameter Node
	6635	You can st ore how fa r you have progresse d with a t ask you ar e performi ng in the callback b y using a checkpoint parameter node. The $$UPCP^XP DUTL(): Up date Check point func tion updat es the val ue of a ch eckpoint’s parameter node; the $$PARCP^X PDUTL(): G et Checkpo int Parame ter functi on retriev es the val ue of a ch eckpoint’s parameter node.
	6636	Being able to update and retri eve a para meter with in a check point can be quite u seful. For example, if you are convertin g each ent ry in a fi le, as you progress through th e file you can updat e the chec kpoint’s p arameter n ode with t he Interna l Entry Nu mber (IEN) of each e ntry as yo u convert it. Then, if the con version er rors out a nd has to be re-star ted, you c an WRITE y our checkp oint callb ack in suc h a way th at it alwa ys retriev es the las t complete d IEN stor ed in the checkpoint ’s paramet er node. T hen, it ca n process entries in the file starting f rom the la st complet ed IEN, ra ther than the first entry in t he file. T his is one example o f how you can save t he site ti me and avo id re-proc essing.
	6637	The pre-in stall API in this ex ample is P RE^ZZUSER2 ; the post -install A PI is POST ^ZZUSER2.
	6638	Figure 71: KIDS—Usin g checkpoi nts with c allbacks: combined p re- and po st-install routine
	6639	ZZUSER2 ;RON TES T 1.0 PRE AND POST I NSTALL
	6640	;;1.0
	6641	;buil d checkpoi nts for PR E
	6642	PRE N %
	6643	S %=$ $NEWCP^XPD UTL(“ZZUSE R1”,“PRE1^ ZZUSER2”,“ C-”)
	6644	Q
	6645	PRE1 ;chec k terminal type file
	6646	N DA, UPDATE,NAM E
	6647	;quit if answer NO to que stion 1
	6648	Q:’XP DQUES(“PRE 1”)
	6649	S UPD ATE=XPDQUE S(“PRE2”)
	6650	;writ e message to user ab out task
	6651	D BME S^XPDUTL(“ Checking T erminal Ty pe File”)
	6652	;get parameter value to i nitialize NAME
	6653	S NAM E=$$PARCP^ XPDUTL(“ZZ USER1”)
	6654	F S NAME=$O(^% ZIS(2,“B”, NAME)) Q:$ E(NAME,1,2 )’=“C-” D
	6655	.S DA =+$O(^%ZIS (2,“B”,NAM E,0))
	6656	.I DA ,$D(^%ZIS( 2,DA,1)),$ P(^(1),U,5 )]“” D MES ^XPDUTL(NA ME_” still has data in field 5 ”) S:UPDAT E $P(^%ZIS (2,DA,1),U ,5)=“”
	6657	.;upd ate parame ter NAME
	6658	.S %= $$UPCP^XPD UTL(“ZZUSE R1”,NAME)
	6659	Q
	6660	;buil d checkpoi nts for PO ST
	6661	POST N %
	6662	S %=$ $NEWCP^XPD UTL(“ZZUSE R1”,“POST1 ^ZZUSER2”)
	6663	S %=$ $NEWCP^XPD UTL(“ZZUSE R2”)
	6664	Q
	6665	POST1 ;check v ersion mul tiple
	6666	N DA, VER,%
	6667	;quit if answer NO to que stion 1
	6668	Q:’XP DQUES(“POS T1”)
	6669	;writ e message to user ab out task
	6670	D BME S^XPDUTL(“ Checking P ackage Fil e”)
	6671	;get parameter value to i nitialize DA
	6672	S DA= +$$PARCP^X PDUTL(“ZZU SER1”)
	6673	F S DA=$O(^DIC (9.4,DA)) Q:’DA D
	6674	.S VE R=+$$PARCP ^XPDUTL(“Z ZUSER2”)
	6675	.F S VER=$O(^D IC(9.4,DA, 22,VER)) Q :’VER D
	6676	..;he re is wher e we could do someth ing
	6677	..;up date param eter VER
	6678	..S % =$$UPCP^XP DUTL(“ZZUS ER2”,VER)
	6679	.;upd ate parame ter DA
	6680	.S %= $$UPCP^XPD UTL(“ZZUSE R1”,DA),%= $$UPCP^XPD UTL(“ZZUSE R2”,VER)
	6681	Q
	6682
	6683	Checkpoint s without Callbacks (Data Stor age)
	6684	KIDS ignor es checkpo ints that do not hav e callback routines specified. The abili ty to crea te checkpo ints witho ut a callb ack routin e is provi ded mainly as a faci lity for d evelopers to store i nformation during th e pre- or post-insta ll routine . The para meter node of the ch eckpoint s erves as t he data st orage mech anism. It is not saf e to store important informati on in loca l variable s during p re- or pos t-install routines, because in stallation s can now be re-star ted in the middle; v ariables d efined pri or to the restart ma y no longe r be defin ed after a restart.
	6685	An alterna tive use l ets you ex pand the s cope of ch eckpoints without ca llbacks be yond simpl y storing data. If y ou want to manage yo ur own che ckpoints i nstead of letting KI DS manage them, you can create checkpoin ts without callbacks , but use them to di vide your pre- and p ost-instal l routine into phase s. Rather than havin g KIDS exe cute and c omplete th em (as hap pens when the checkp oint has a callback routine), you would then be re sponsible for execut ing and co mpleting t he checkpo ints. In t his style of coding a pre- or a post-ins tall routi ne, you wo uld:
	6686	Check if e ach checkp oint exist s ($$VERCP ^XPDUTL(): Verify Ch eckpoint); if it doe s not exis t, create it ($$NEWC P^XPDUTL() : Create C heckpoint) .
	6687	Retrieve t he current checkpoin t paramete r as the s tarting po int if you want to ( $$PARCP^XP DUTL(): Ge t Checkpoi nt Paramet er); do th e work for the check point; upd ate the pa rameter no de if you want to ($ $UPCP^XPDU TL(): Upda te Checkpo int).
	6688	Complete t he checkpo int when t he work is finished ($$COMCP^X PDUTL(): C omplete Ch eckpoint).
	6689	Proceed to the next checkpoint .
	6690	You have t o do more work this way than i f you let KIDS manag e the chec kpoints (b y creating the check points wit h callback routines) .
	6691	The KIDS c heckpoint functions that apply when usin g checkpoi nts withou t callback s are summ arized bel ow (listed in alphab etic order ):
	6692	Table 23: KIDS—Funct ions using checkpoin ts without callbacks
	6693	Function
	6694	Descriptio n
	6695	$$COMCP^XP DUTL
	6696	Complete c heckpoint (use durin g pre- or post-insta ll routine ).
	6697	$$NEWCP^XP DUTL
	6698	Create che ckpoint (u se during pre- or po st-install routine).
	6699	$$PARCP^XP DUTL
	6700	Retrieve c heckpoint parameter (use durin g pre-or p ost-instal l routine) .
	6701	$$UPCP^XPD UTL
	6702	Update che ckpoint pa rameter (u se during pre- or po st-install routine).
	6703	$$VERCP^XP DUTL
	6704	Verify if checkpoint exists an d if it ha s complete d (use dur ing pre- o r post-ins tall routi ne).
	6705
	6706	Required B uilds
	6707	In the fou rth screen of the ED IT A BUILD option, y ou can use the Requi red Builds multiple to enter o ther build s (i.e., s oftware ap plications , or patch es) that e ither warn the insta ller when they are m issing or requires t hat they b e installe d before t his build is install ed. Make a n entry in the BUILD file (#9. 6) for tho se softwar e applicat ions or pa tches not installed using KIDS . Include the name a nd version number in the BUILD file (#9. 6) entry.
	6708	REF: For t he action types avai lable, see Table 24.
	6709	At the ins talling si te, KIDS c hecks the PACKAGE fi le (#9.4), VERSION m ultiple, a nd PATCH A PPLICATION HISTORY m ultiple to verify th at the req uired buil d has been installed at that s ite.
	6710	Figure 72: KIDS—Requ ired build s sample
	6711	Edi t a Build PAGE 4 O F 5
	6712	Name: TEST 1.0 TYPE: SING LE PACKAGE
	6713	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------- --
	6714	Instal l Question s
	6715
	6716
	6717
	6718
	6719	Requir ed Builds
	6720	TEST 1.1 Don’t install, remove glo bal
	6721
	6722
	6723	Packa ge File Li nk...: TES T
	6724
	6725	Track Pac kage Natio nally: NO
	6726	__________ __________ __________ __________ __________ __________ __________ __________ ___
	6727
	6728
	6729	COMMAND: Press <P F1>H for h elp Ins ert
	6730
	6731	Table 24: KIDS—Requi red builds installat ion action s
	6732	Installati on Action
	6733	Descriptio n
	6734	WARNING ON LY
	6735	Warns the installer the listed software applicatio n/patch is missing a t the site but allow s the inst allation t o continue . (Display s a WARN ING to t he install er.)
	6736	DON’T INST ALL, LEAVE GLOBAL
	6737	If the lis ted softwa re applica tion/patch is missin g, this ac tion preve nts sites from conti nuing the installati on. It doe s not unlo ad the Tra nsport Glo bal. This allows sit es to inst all the mi ssing item and conti nue with t he install ation with out having to reload the Trans port Globa l.
	6738	DON’T INST ALL, REMOV E GLOBAL
	6739	If the lis ted softwa re applica tion/patch is missin g, this ac tion preve nts sites from conti nuing the installati on. It als o unloads the Transp ort Global .
	6740
	6741	Package Fi le Link
	6742	In the fou rth screen of the ED IT A BUILD option, y ou can lin k your bui ld to an e ntry in th e national PACKAGE f ile (#9.4) . Use this link if y ou want to update th e site’s P ACKAGE fil e (#9.4) w hen the so ftware app lication y ou are cre ating is i nstalled o r if you w ant to use Kernel’s Alpha/Beta Testing m odule. You can only link to a PACKAGE fi le (#9.4) entry that is the sa me name (m inus the v ersion num ber) as th e build yo u are crea ting.
	6743	If you spe cify a PAC KAGE file (#9.4) ent ry in the PACKAGE FI LE LINK fi eld, and t he install ing site d oes not ha ve a match ing entry in their P ACKAGE fil e (#9.4), KIDS creat es a new e ntry in th e installi ng site’s PACKAGE fi le (#9.4).
	6744	KIDS check s for dupl icate vers ion number s and patc h names wh en updatin g the PACK AGE file ( #9.4). Whe n you link to an ent ry in the PACKAGE fi le (#9.4), your inst allation a utomatical ly updates the VERSI ON multipl e in the i nstalling site’s cor responding PACKAGE f ile (#9.4) entry. KI DS makes a new entry in the VE RSION mult iple for t he version of the so ftware app lication y ou are ins talling. K IDS fills in the fol lowing fie lds in the new VERSI ON entry:
	6745	VERSION
	6746	DATE DISTR IBUTED
	6747	DATE INSTA LLED AT TH IS SITE
	6748	INSTALLED BY
	6749	DESCRIPTIO N OF ENHAN CEMENTS
	6750	PATCH APPL ICATION HI STORY
	6751	PATCH APPL ICATION HI STORY
	6752	DATE APPLI ED
	6753	APPLIED BY
	6754	DESCRIPTIO N
	6755	KIDS saves patch nam es along w ith their sequence n umbers in the PATCH APPLICATIO N HISTORY multiple ( this funct ionality w as added w ith patch XU8.030) . The Patc h Applicat ion Histor y sample ( Figure 73) shows a l ist of pat ch names w ith and wi thout sequ ence numbe rs. Those patches wi thout sequ ence numbe rs were en tered prio r to patch XU8.030 , since no sequence numbers ar e evident.
	6756	In additio n, you can choose to update th e followin g fields a t the top level of t he Nationa l PACKAGE file (#9.4 ):
	6757	Table 25: KIDS—Natio nal PACKAG E file fie ld updates
	6758	PACKAGE Fi le (#9.4) Field Name
	6759	Descriptio n
	6760	PRIMARY HE LP FRAME
	6761	Select the primary h elp frame for the so ftware app lication.
	6762	AFFECTS RE CORD MERGE
	6763	(multiple) Select fi les that, if merged, affect th is softwar e applicat ion.
	6764	ALPHA/BETA TESTING
	6765	There are two possib le respons es:
	6766	YES—This s oftware ap plication is current ly in alph a or beta test and y ou want to track opt ion usage and errors relating to this so ftware app lication a t the site s.
	6767	NO—You wan t to disco ntinue tra cking of a lpha or be ta testing at the si tes.
	6768
	6769	Beyond the se fields, KIDS does not suppo rt maintai ning any o ther infor mation in the PACKAG E file (#9 .4).
	6770	Figure 73: KIDS—Patc h Applicat ion Histor y sample
	6771	Select PA TCH APPLIC ATION HIST ORY: 48// ?
	6772	Answer wi th PATCH A PPLICATION HISTORY
	6773	Choose fro m:
	6774
	6775	Patches wi thout sequ ence numbe rs means t hat they w ere entere d prior to Kernel pa tch XU8.0 30.
	6776	Patches wi thout sequ ence numbe rs means t hat they w ere entere d prior to Kernel pa tch XU8.0 30.
	6777	27
	6778	39
	6779	41
	6780	42
	6781	48
	6782	45 SEQ #41
	6783	46 SEQ #42
	6784	47 SEQ #43
	6785
	6786	You m ay enter a new PATCH APPLICATI ON HISTORY , if you w ish
	6787	Answe r must be 8-15 chara cters in l ength.
	6788
	6789	Select P ATCH APPLI CATION HIS TORY: 48// <Enter>
	6790	PATCH APPLICATIO N HISTORY: 48// <Ent er>
	6791	DATE A PPLIED: SE P 20,1996/ / <Enter>
	6792	APPLIE D BY: XUUS ER,NINETY/ / <Enter>
	6793	DESCRI PTION:
	6794	1>This c ontains fi xes relate d to outpu t fixes fo r the PCMM software
	6795	2>(distr ibuted as SD5.341) .
	6796	3>
	6797	4>Both S D5.341 a nd SD5.3 45 must be installed prior to loading th is
	6798	5>patch.
	6799
	6800	Track Pack age Nation ally
	6801	The fourth screen of the EDIT A BUILD op tion also lets you c hoose whet her to sen d a messag e to the N ational PA CKAGE file (#9.4) on FORUM, ea ch time th e software applicati on is inst alled at a site. If you enter YES in the TRACK PAC KAGE NATIO NALLY fiel d, KIDS se nds a mess age to FOR UM when a site insta lls the so ftware app lication, provided t he followi ng conditi ons are me t:
	6802	The PACKAG E FILE LIN K field in the build APIs to a n entry in the PACKA GE file (# 9.4).
	6803	The softwa re applica tion is in stalled at a site th at is a pr imary VA d omain.
	6804	The softwa re applica tion is in stalled in a product ion UCI.
	6805	Answering NO to TRAC K PACKAGE NATIONALLY (or leavi ng it blan k) means t hat KIDS d oes not se nd a messa ge to FORU M.
	6806	Alpha/Beta Tracking
	6807	Kernel pro vides a me chanism fo r tracking and monit oring inst allation a nd option usage duri ng the alp ha and bet a testing phases of VistA soft ware appli cations. T his tool i s primaril y intended for appli cation dev elopers to use in mo nitoring t he testing process a t local te st sites.
	6808	NOTE: In V A terminol ogy, “Alph a” and “Be ta” testin g are defi ned as fol lows:
	6809	Alpha Test ing—VistA test softw are applic ation that is runnin g in a Tes t account.
	6810	Beta Testi ng—VistA t est softwa re applica tion that is running in a Prod uction acc ount.
	6811	Alpha/Beta Tracking provides t he followi ng service s to both developers and syste m administ rators:
	6812	Notificati on when a new alpha or beta so ftware ver sion is in stalled at a site.
	6813	Periodic o ption usag e reports for alpha or beta op tions bein g tracked.
	6814	Periodic l istings of errors in the softw are’s name space that are curre ntly in al pha or bet a test at the site.
	6815	The Alpha/ Beta Track ing of opt ion usage is transpa rent to us ers. If th e option c ounter is turned on, it record s the numb er of time s an optio n is invok ed within the menu s ystem when entered i n the usua l way via ^XUS. Opti ons are no t counted when navig ated past in the cou rse of men u jumping. Also, the counter i s not set when enter ing the me nu system with the d evelopers ^XUP utili ty.
	6816	Alpha/Beta tracking data is st ored in th e followin g Multiple s in the K ERNEL SYST EM PARAMET ERS file ( #8989.3), which is s tored in t he ^XTV gl obal:
	6817	Table 26: Alpha/Beta Tracking— KERNEL SYS TEM PARAME TERS file (#8989.3) field setu p for KIDS
	6818	Alpha/Beta Tracking Fields:KER NEL SYSTEM PARAMETER S File (#8 989.3)
	6819	Descriptio n
	6820	ALPHA/BETA TEST PACK AGE Multip le (#32)
	6821	This field stores th e list of software n amespaces that are c urrently i n alpha or beta test at the si te.
	6822	ALPHA,BETA TEST OPTI ON Multipl e (#33)
	6823	This field keeps a l og of usag e of the o ptions ass ociated wi th an alph a or beta test of Vi stA softwa re based o n the name space indi cated for the alpha or beta te st softwar e in the . ALPHA/BETA TEST PACK AGE Multip le field ( #32). This field sto res pointe rs to entr ies in the OPTION fi le (#19).
	6824
	6825	If there a re any ent ries in th ese Multip les, the m enu system ’s XQABTST variable is set and the optio ns are tra cked.
	6826	Each time any subseq uent test software i s loaded, the curren t alpha/be ta data is sent to t he data tr acker (e.g ., develop er) and th e alpha/be ta data is purged fr om all Mul tiples.
	6827	Initiating Alpha/Bet a Tracking
	6828	In order t o initiate and setup Alpha/Bet a Tracking at a test site, dev elopers sh ould perfo rm the fol lowing pro cedures:
	6829	Create the build ent ry for the VistA sof tware that is export ed to site s.
	6830	Turn on Al pha/Beta T racking—In the “Pack age File L ink…” sect ion in the fourth Sc reenMan fo rm of the build entr y. Develop ers can tu rn on Alph a/Beta Tra cking by e ntering YE S at the “ BUILD TRAC K PACKAGE NATIONALLY :” prompt. ALPHA/BET A TESTING field (#20 ) in the B UILD file (#9.6).
	6831	Edit THE B UILD file Entries—Hi ghlight th e software name and press the <Enter> ke y. KIDS pl aces you i n a Screen Man form t hat lets y ou edit th e followin g Alpha/Be ta Trackin g-related fields in the BUILD file (#9.6 ):
	6832	Table 27: Alpha/Beta Tracking— BUILD file (#9.6) fi eld setup for KIDS
	6833	Alpha/Beta Tracking Fields:BUI LD File (# 9.6)
	6834	Descriptio n
	6835	ALPHA/BETA TESTING ( #20)
	6836	This field initiates Alpha/Bet a Tracking . Develope rs should enter YES in this fi eld to act ivate Alph a/Beta Tra cking.
	6837	INSTALLATI ON MESSAGE (#21)
	6838	This field sends an installati on message when the VistA soft ware appli cation is installed at a site. Developer s should a nswer YES if you wan t the inst allation m essage sen t to the m ail group specified in the ADD RESS FOR U SAGE REPOR TING field (#22) in the BUILD file (#9.6 ).
	6839	ADDRESS FO R USAGE RE PORTING (# 22)
	6840	This field should be set to th e address of the Mai lMan mail group at t he develop er’s domai n. This ma il group a ddress is where inst allation a nd option usage mess ages are s ent by the Alpha/Bet a Tracking code. Als o, the dom ain specif ied in the address i s where se rver reque sts are se nt from th e sites to report er rors.
	6841	PACKAGE NA MESPACE OR PREFIX fi eld (#23)
	6842	This field is where you identi fy the alp ha/beta Vi stA softwa re applica tion names paces to b e tracked.
	6843
	6844	NOTE: At A lpha/Beta Tracking t ermination , these fi elds in th e BUILD fi le (#9.6) need to re main popul ated so th e software code know s where to send the final repo rt.
	6845	Set up the server op tion at th e developm ent domain . This opt ion must b e set up c orrectly—I n order to track err ors at tes t sites, m ake sure t hat the XQ AB ERROR L OG SERVER server opt ion reside s at your developmen t site, wh ich should be the do main speci fied in th e ADDRESS FOR USAGE REPORTING field (#22 ) in the B UILD file (#9.6) for the softw are build entry.This option pr ocesses se rver reque sts from t he test si tes, from the Errors Logged in Alpha/Bet a Test (QU EUED) opti on [XQAB E RROR LOG X MIT]. The server sto res the da ta from th e requests into the XQAB ERROR S LOGGED f ile (#8991 .5).
	6846	REF: For m ore inform ation on t he Errors Logged in the Alpha/ Beta Test (Queued) o ption, see the “Erro r Tracking —Alpha/Bet a Software Releases” section.
	6847	Schedule t he Errors Logged in the Alpha/ Beta Test (Queued) o ption [XQA B ERROR LO G XMIT] to run at si tes to gat her errors and repor t these to the devel opment ser ver.
	6848	REF: For m ore inform ation on t he Errors Logged in the Alpha/ Beta Test (Queued) o ption, see the “Erro r Tracking —Alpha/Bet a Software Releases” section.
	6849	Schedule t he Send Al pha/Beta U sage to Pr ogrammers option [XQ AB AUTO SE ND] at the sites to send mail messages c ontaining option usa ge.
	6850	REF: For m ore inform ation on t he Send Al pha/Beta U sage to Pr ogrammers option, se e the “Sen d Alpha/Be ta Usage t o Programm ers Option ” section.
	6851	Error Trac king—Alpha /Beta Soft ware Relea ses
	6852	As well as tracking option usa ge and ins tallations , Kernel a lso lets d evelopers track erro rs that oc cur in the namespace of the al pha- or be ta-tracked software. To report these err ors to dev elopers, t he site sh ould sched ule the Er rors Logge d in Alpha /Beta Test (QUEUED) option [XQ AB ERROR L OG XMIT]. This optio n cannot b e run dire ctly; it i s located on the ZTM QUEUABLE O PTIONS men u, which i s not on a ny Kernel menu tree, as shown below:
	6853	Figure 74: KIDS—Erro rs Logged in Alpha/B eta Test ( QUEUED) op tion
	6854	ZTMQUEUABL E OPTIONS [ZTMQUEUAB LE OPTIONS ]
	6855	Erro rs Logged in Alpha/B eta Test ( QUEUED)[XQ AB ERROR L OG XMIT]
	6856
	6857	The Errors Logged in Alpha/Bet a Test (QU EUED) opti on [XQAB E RROR LOG X MIT] ident ifies any errors ass ociated wi th an appl ication th at is in e ither alph a or beta test. It c ollects er ror inform ation and sends it t o a server at the de velopment domain. Th e develope r may ask sites to s chedule th is option to run at a specifie d frequenc y, usually nightly. For exampl e, develop ers may in struct tes t sites to schedule it as a ta sk to run daily, aft er midnigh t.
	6858	The identi fied error s are comb ined in a mail messa ge that in cludes the following informati on:
	6859	Type of er ror
	6860	Routine in volved
	6861	Date (usua lly the pr evious day )
	6862	Option tha t was bein g used at the time o f the erro r
	6863	Number of times the error was logged
	6864	Volume
	6865	UCI
	6866	NOTE: The volume and UCI are i ncluded so that stat ions with error logs being mai ntained on different CPUs can run the ta sk on each different system.
	6867	Monitoring Alpha/Bet a Tracking
	6868	There are a number o f options available to sites u sed to mon itor the p rogress of alpha or beta testi ng. These options ar e located on the Alp ha/Beta Te st Option Usage Menu [XQAB MEN U], which is located on the Op erations M anagement menu [XUSI TEMGR]:
	6869	Figure 75: Alpha/Bet a Test Opt ion Usage Menu optio ns
	6870	Operations Managemen t ...[XUSI TEMGR]
	6871	Alpha/Be ta Test Op tion Usage Menu ... [XQAB MENU ]
	6872	Actual Usage of Alpha/Beta Test Opti ons[XQAB A CTUAL OPTI ON USAGE]
	6873	Low Us age Alpha/ Beta Test Options[XQ AB LIST LO W USAGE OP TS]
	6874	Print Alpha/Beta Errors (D ate/Site/N um/Rou/Err )[XQAB ERR DATE/SITE /NUM/ROU/E RR]
	6875	Send A lpha/Beta Usage to P rogrammers [XQAB AUT O SEND]
	6876
	6877	These opti ons are de scribed in the secti ons that f ollow.
	6878	Usage Repo rt Options
	6879	To get usa ge reports during th e alpha/be ta testing of softwa re that is making us e of the o ption coun ter, syste m administ rators can review th e tallies with the f ollowing o ptions:
	6880	Actual Usa ge of Alph a/Beta Tes t Options [XQAB ACTU AL OPTION USAGE]
	6881	Low Usage Alpha/Beta Test Opti ons [XQAB LIST LOW U SAGE OPTS]
	6882	Actual Usa ge of Alph a/Beta Tes t Options Option
	6883	To get act ual usage reports du ring the a lpha/beta testing of software that is ma king use o f the opti on counter , system a dministrat ors can re view the t allies wit h the Actu al Usage o f Alpha/Be ta Test Op tions opti on [XQAB A CTUAL OPTI ON USAGE]. ADPACs ma y also be interested in being able to ge nerate thi s informat ion. Figur e 76 shows a printou t of the a ctual usag e of optio ns within the XU nam espace:
	6884	Figure 76: Actual Us age of Alp ha/Beta Te st Options option—Sa mple Optio n Usage re port
	6885	OPTION USAGE SIN CE 08-05-9 2
	6886
	6887	XUSERINQ I 44 User Inqui ry
	6888	XUUSERDISP R 49 Display Us er Charact eristics
	6889	XUFILEACCE SS M 50 File Acces s Manageme nt
	6890	XUSERBLK R 51 Grant Acce ss by Prof ile
	6891	XUTIME A 53 Time
	6892	XUHALT A 71 Halt
	6893	XUMAINT M 83 Menu Manag ement
	6894	XUSITEMGR M 86 Operations Managemen t
	6895	XUSEREDITS ELF R 87 Edit User Characteri stics
	6896	XUSERTOOLS M 129 User’s Too lbox
	6897	XUSEREDIT A 175 Edit an Ex isting Use r
	6898	XUPROG M 191 Programmer Options
	6899	XUSER M 265 User Edit
	6900	XUPROGMODE R 268 Programmer mode
	6901
	6902	Low Usage of Alpha/B eta Test O ptions Opt ion
	6903	A similar report can be obtain ed of low usage opti ons since the curren t version of the tra cked softw are was in stalled, u sing the L ow Usage o f Alpha/Be ta Test Op tions opti on [XQAB L IST LOW US AGE OPTS].
	6904	Print Alph a/Beta Err ors (Date/ Site/Num/R ou/Err) Op tion
	6905	The Print Alpha/Beta Errors (D ate/Site/N um/Rou/Err ) option [ XQAB ERR D ATE/SITE/N UM/ROU/ERR ] is used at the dev elopment d omain, to print erro r informat ion collec ted from s ites. It d oes not re port meani ngful info rmation wh en used at a site.
	6906	Send Alpha /Beta Usag e to Progr ammers Opt ion
	6907	At any tim e during a lpha/beta testing, s ystem admi nistrators can send an interim summary m essage bac k to the d evelopers, with the Send Alpha /Beta Usag e to Progr ammers opt ion [XQAB AUTO SEND] .
	6908	To receive option us age report s, develop ers should instruct the sites to schedul e this opt ion to run at whatev er frequen cy desired in order to receive option us age report s. It may be conveni ent to sch edule this task to r un, perhap s on a wee kly basis; however, the develo per may as k system a dministrat ors to sch edule it t o run at a different specified frequency . This opt ion can al so be run manually b y the site s to send option usa ge informa tion.
	6909	Mail messa ges are se nt to the mail group and domai n specifie d by the n ational ap plication developer in the bui ld entry f or the ADD RESS FOR U SAGE REPOR TING field (#22) in the BUILD file (#9.6 ) when the y exported the softw are.
	6910	NOTE: Deve lopers/Sys tem Admini strators, make sure that this mail group exists at the devel opment dom ain!
	6911	Terminatin g Alpha/Be ta Trackin g
	6912	Alpha/Beta Tracking, once init iated for a VistA so ftware app lication, must be tu rned off w hen the fi nal versio n of the s oftware ap plication is release d national ly (produc tion). It is the dev eloper’s r esponsibil ity to man ually stop Alpha/Bet a Tracking , terminat e the audi t, and pur ge the dat a when app ropriate p rior to na tional rel ease. Howe ver, syste m administ rators can also term inate Alph a/Beta Tra cking at t he local l evel:
	6913	Local (Tes t) Softwar e—Develope r or syste m administ rators is responsibl e for term inating Al pha/Beta T racking at the local site.
	6914	National ( Production ) Software —Developer s are resp onsible fo r terminat ing Alpha/ Beta Track ing for so ftware tha t is relea sed nation ally.
	6915	Informatio n stored d uring Alph a/Beta Tra cking is p urged each time a su bsequent t est versio n of the s oftware is installed . A final summary re port of op tion usage is prepar ed and sen t to the d eveloper’s mail grou p just bef ore the pu rge.
	6916	Local (Tes t) Softwar e Option U sage—Termi nating Alp ha/Beta Tr acking
	6917	For test v ersions of the softw are applic ation that is loaded locally ( Test/Produ ction acco unts), it is the dev eloper or system adm inistrator ’s respons ibility to stop Alph a/Beta Tra cking, ter minate the audit, an d purge th e data fro m the KERN EL SYSTEM PARAMETERS file (#89 89.3) when appropria te. There is no Kern el option to purge l ocally col lected opt ion counts ; purge th e data via a global KILL. If a subsequen t software version r elease is another te st version , Alpha/Be ta Trackin g is autom atically r e-initiate d and trac king count s are rese t back to zero.
	6918	NOTE: If t he Alpha/B eta testin g is set t o YES, any subsequen t software version s hould be c onsidered another te st softwar e version. If the Al pha/Beta t esting is still set to NO, the n the subs equent sof tware vers ion should be consid ered a pro duction/re lease soft ware versi on.
	6919	To manuall y stop Alp ha/Beta Tr acking at an individ ual site, developers or system administr ators can use the En ter/Edit K ernel Site Parameter s option [ XUSITEPARM ] located on the Ker nel Manage ment Menu [XUKERNEL] to remove the desir ed entries from the ALPHA/BETA TEST PACK AGE Multip le (#32) a nd ALPHA,B ETA TEST O PTION Mult iple field (#33) fie lds in the KERNEL SY STEM PARAM ETERS file (#8989.3) :
	6920	Figure 77: Enter/Edi t Kernel S ite Parame ters—Sampl e user dia logue
	6921	Select Ker nel Manage ment Menu Option: EN TER/EDIT K ERNEL SITE PARAMETER S
	6922
	6923	Note: the TaskMan si te paramet ers have b een moved out of thi s file.
	6924	Use the Ed it TaskMan Parameter s option t o edit tho se values.
	6925
	6926	DEFAULT # OF ATTEMPT S: 3// ^AL PHA BETA T EST PACKAG E
	6927	Select ALP HA/BETA TE ST PACKAGE : ZZLOCAL/ / @
	6928	SURE YO U WANT TO DELETE THE ENTIRE AL PHA,BETA T EST PACKAG E? Y
	6929	Select ALP HA/BETA TE ST PACKAGE : <Enter>
	6930	Select ALP HA,BETA TE ST OPTION: ZZSAMPLE/ / @
	6931	SURE YO U WANT TO DELETE THE ENTIRE AL PHA,BETA T EST OPTION ? Y
	6932
	6933	National ( Production ) Software Option Us age—Termin ating Alph a/Beta Tra cking
	6934	For the fi nal versio n of the s oftware ap plication that is to be releas ed nationa lly (produ ction), it is the de veloper’s responsibi lity to ma nually sto p Alpha/Be ta Trackin g, termina te the aud it, and pu rge the da ta from th e local Te st/Product ion accoun ts when ap propriate prior to n ational re lease.
	6935	NOTE: For more infor mation on how to ter minate Alp ha/Bea Tra cking at l ocal test sites, see the “Loca l (Test) S oftware Op tion Usage —Terminati ng Alpha/B eta Tracki ng” sectio n in this section.
	6936	To manuall y stop Alp ha/Beta Tr acking of nationally released software, developers must ente r NO in th e ALPHA/BE TA TESTING field (#2 0) in the BUILD file (#9.6) fo r the fina l build of the produ ction soft ware. When the sites install t he build, Alpha/Beta Tracking is shut of f.
	6937	Applicatio n Programm ing Interf ace (API)
	6938	Several AP Is are ava ilable for developer s to work with KIDS. These API s are desc ribed belo w.
	6939	NOTE: For all output during pr e- and pos t-installs , use the MES^XPDUTL (): Output a Message and BMES^ XPDUTL(): Output a M essage wit h Blank Li ne APIs. T hese funct ions WRITE output to both the INSTALL fi le (#9.7) and the ou tput devic e.
	6940	UPDATE^XPD ID(): Upda te Install Progress Bar
	6941	Reference Type:Suppo rted
	6942	Category:K IDS
	6943	ICR #:2172
	6944	Descriptio n:This API updates t he progres s bar to s how the pe rcentage c omplete fo r the inst allation o f the curr ent number of items specified (i.e., “n” input par ameter).
	6945	Format:UPD ATE^XPDID( n)
	6946	Make sure to perform the follo wing steps before ca lling this API:
	6947	NEW all no n-namespac ed variabl es.
	6948	Set all in put variab les.
	6949	Call the A PI.
	6950	Input Vari ables:XPDI DTOT:(requ ired) This variable is the tot al number of items t hat are be ing update d.
	6951	Input Para meters:n:( required) The curren t number o f items be ing update d.
	6952	Output:non e.
	6953
	6954	Example
	6955	If you are convertin g 100 reco rds and wa nt to upda te the use r every ti me you hav e complete d 10% of t he records you would do the fo llowing:
	6956
	6957	>Set XPDID TOT=100
	6958	>F%=1:1:10 0 D CONVER T I’(%#10) D UPDATE^ XPDID(%)
	6959
	6960	EN^XPDIJ() : Task Off KIDS Inst all
	6961	Reference Type:Contr olled Subs cription
	6962	Category:K IDS
	6963	ICR #:2243
	6964	Descriptio n:This API can be us ed with XP DA and is defined to task off a KIDS ins tall. This is useful if a larg e conversi on needs t o run in t he backgro und while users are back on th e system. For exampl e, the fir st KIDS bu ild can in stall a ne w version of softwar e, then ta sk off a s econd clea nup/conver sion build . This all ows users back onto the system , because the new ve rsion inst all comple tes and un locks opti ons and pr otocols. M eanwhile, the cleanu p runs in the backgr ound under KIDS and makes use of KIDS ch eckpoints, restart u pon failur e, and mes sage loggi ng that ca n later be accessed in the Ins tall File Print.
	6965	Format:EN^ XPDIJ(xpda )
	6966	Input Para meters:xpd a:(require d) Interna l entry nu mber of th e build to be tasked in the IN STALL file (#9.7).
	6967	Output:non e.
	6968
	6969	$$PKGPAT^X PDIP(): Up date Patch History
	6970	Reference Type:Suppo rted
	6971	Category:K IDS
	6972	ICR #:2067
	6973	Descriptio n:This ext rinsic fun ction upda tes the PA TCH APPLIC ATION HIST ORY field (#1105, Mu ltiple) of the VERSI ON field ( #22, Multi ple) in th e PACKAGE file (#9.4 ). This fu nction can be used d uring the Pre- or Po st-Install routine.
	6974	Format:$$P KGPAT^XPDI P(software _ien,versi on,.x)
	6975	Input Para meters:sof tware_ien: (required) The softw are file e ntry Inter nal Entry Number (IE N) in the PACKAGE fi le (#9.4).
	6976	version:(r equired) T his is the software version nu mber. It m ust contai n a decima l (e.g., 8 .0).
	6977	.x:(requir ed) This p arameter i s required .
	6978	Output:ret urns:Retur ns:
	6979	version ie n^patch ie n
	6980
	6981	BMES^XPDUT L(): Outpu t a Messag e with Bla nk Line
	6982	Reference Type:Suppo rted
	6983	Category:K IDS
	6984	ICR #:1014 1
	6985	Descriptio n:During K IDS instal lations, t his API ou tputs a me ssage stri ng to the installati on device. A message is also r ecorded in the INSTA LL file (# 9.7) entry for the i nstallatio n. It is s imilar to the MES^XP DUTL(): Ou tput a Mes sage API, except tha t it outpu ts a blank line befo re it outp uts the me ssage, and it does n ot take ar rays.
	6986	Format:BME S^XPDUTL(m sg)
	6987	Input Para meters:msg :(required ) String t o output.
	6988	Output:ret urns:Retur ns a messa ge string preceded b y a blank line to th e installa tion devic e.
	6989
	6990	$$COMCP^XP DUTL(): Co mplete Che ckpoint
	6991	Reference Type:Suppo rted
	6992	Category:K IDS
	6993	ICR #:1014 1
	6994	Descriptio n:During K IDS instal lations, t his extrin sic functi on complet es a check point, in pre- or po st-install routines. Use this only to co mplete che ckpoints t hat do not have call back routi nes. If th e checkpoi nt has a c allback ro utine, KID S itself c ompletes t he checkpo int. You c an only co mplete che ckpoints t hat are fo r the same installat ion phase (pre-insta ll or post -install) that you a re current ly in.
	6995	Use this A PI only fo r checkpoi nts with n o callback . KIDS com pletes che ckpoints t hat have a callback.
	6996	Format:$$C OMCP^XPDUT L(name)
	6997	Input Para meters:nam e:(require d) Checkpo int name.
	6998	Output:ret urns:Retur ns:
	6999	1—Successf ully compl eted check point.
	7000	0—Error co mpleting c heckpoint.
	7001
	7002	$$CURCP^XP DUTL(): Ge t Current Checkpoint Name/IEN
	7003	Reference Type:Suppo rted
	7004	Category:K IDS
	7005	ICR #:1014 1
	7006	Descriptio n:This ext rinsic fun ction is u sed during KIDS inst allations. Use this extrinsic function t o return t he name of the curre nt checkpo int. It ca n be usefu l if, for example, y ou use the same tag^ routine AP I for more than one callback. Using this function, you can d etermine w hich callb ack you ar e in.
	7007	Use this A PI only fo r checkpoi nts with a callback. It return s the NULL string if you call it when wo rking with a checkpo int with n o callback (in which case, you would rea lly be in either the pre- or p ost-instal l routine) .
	7008	Format:$$C URCP^XPDUT L(format)
	7009	Input Para meters:for mat:(requi red) Pass as zero (0 ) to retur n checkpoi nt name. P ass as 1 t o return c heckpoint Internal E ntry Numbe r (IEN).
	7010	Output:ret urns:Retur ns:
	7011	Checkpoint Name—The current ch eckpoint n ame.
	7012	NULL Strin g—If not c urrently i n a checkp oint callb ack.
	7013
	7014	$$INSTALDT ^XPDUTL(): Return Al l Install Dates/Time s
	7015	Reference Type:Suppo rted
	7016	Category:K IDS
	7017	ICR #:1014 1
	7018	Descriptio n:This ext rinsic fun ction retr ieves all dates/time s that an install wa s performe d for a gi ven instal l name in the INSTAL L file (#9 .7). It re turns the results in an array. This API was releas ed with Ke rnel patch XU8.049 1.
	7019	Format:$$I NSTALDT^XP DUTL(insta ll,.result )
	7020	Input Para meters:ins tall:(requ ired) Name of instal l in the I NSTALL fil e (#9.7).
	7021	.result:(r equired) P assed by r eference, the name o f the arra y to retur n values.
	7022	Output Par ameters:.r esult:Retu rns the nu mber of re cords in t he result array:
	7023	result=num ber of rec ords.
	7024	result(int ernal date /time)=“TE ST#^SEQ#” (Fields 61 ^62 from I NSTALL fil e [#9.7]).
	7025
	7026	Example
	7027	>W $$INSTA LDT^XPDUTL (“XU8.04 91”, .RSLT )
	7028	1
	7029	>ZW RSLT
	7030	RSLT=1
	7031	RSLT(30803 18.092151) =“1^”
	7032
	7033	$$LAST^XPD UTL(): Las t Software Patch
	7034	Reference Type:Suppo rted
	7035	Category:K IDS
	7036	ICR #:1014 1
	7037	Descriptio n:This ext rinsic fun ction retu rns the la st patch a nd the dat e it was a pplied to the softwa re. The pa tch also i ncludes th e Sequence # if the last patch was a rel eased patc h.
	7038	NOTE: This API can b e used out side of KI DS.
	7039	Format:$$L AST^XPDUTL (x[,y][,z] )
	7040	Input Para meters:x:( required) Software n ame or sof tware name space with in quotes (e.g., “KE RNEL” or “ XU”).
	7041	y:(optiona l) Full so ftware ver sion numbe r with dec imal point entered w ithin quot es (e.g., “8.0”). Th e current version is assumed i f this par ameter is not suppli ed.
	7042	z:(optiona l) This pa rameter wa s added wi th Kernel patch XU8 .0559. If set to 1, then only the last released p atch infor mation is returned.
	7043	Output:ret urns:Retur ns the las t patch in formation in a caret -delimited string:
	7044	nnn^yyymmd d—Unreleas ed patch, where “nnn ” = patch number and “yyymmdd” = date in VA FileMa n format.
	7045	nnn Seq #n nn^yyymmdd —Released patch, whe re “nnn” = patch num ber, “Seq #nnn” = se quence num ber for re leased pat ch, and “y yymmdd” = date in VA FileMan f ormat.
	7046	-1—If eith er the sof tware or v ersion doe s not exis t or no pa tches have been appl ied.
	7047
	7048	Examples
	7049	Example 1
	7050	>S X=“KERN EL”
	7051
	7052	>S Y=“8.0”
	7053
	7054	>W $$LAST^ XPDUTL(X,Y )
	7055	543^311050 3
	7056
	7057	Example 2
	7058	>S X=“KERN EL”
	7059
	7060	>S Y=“8.0”
	7061
	7062	>S Z=1
	7063
	7064	>W $$LAST^ XPDUTL(X,Y ,Z)
	7065	431 SEQ #4 53^3110425 .122831
	7066
	7067	Example 3
	7068	>S X=“KERN EL”
	7069
	7070	>S Y=“9.0”
	7071
	7072	>S Z=1
	7073
	7074	>-1
	7075
	7076	For this e xample, si nce there is no Kern el 9.0 the expected result is -1.
	7077	MES^XPDUTL (): Output a Message
	7078	Reference Type:Suppo rted
	7079	Category:K IDS
	7080	ICR #:1014 1
	7081	Descriptio n:During K IDS instal lations, t his API ou tputs a me ssage stri ng to the installati on device. A message is also r ecorded in INSTALL f ile (#9.7) entry for the insta llation.
	7082	Format:MES ^XPDUTL([. ]msg)
	7083	Input Para meters:[.] msg:(requi red) Messa ge string to output, either in a variabl e or passe d by refer ence as an array of strings.
	7084	Output:ret urns:Retur ns a messa ge string to the ins tallation device.
	7085
	7086	$$NEWCP^XP DUTL(): Cr eate Check point
	7087	Reference Type:Suppo rted
	7088	Category:K IDS
	7089	ICR #:1014 1
	7090	Descriptio n:During K IDS instal lations—in Pre- or P ost-instal l routines , this ext rinsic fun ction crea tes a chec kpoint. Th e checkpoi nt is stor ed in the INSTALL fi le (#9.7).
	7091	Pre-and po st-install checkpoin ts are sto red separa tely, so y ou can use the same name for a pre- and post-insta ll checkpo int if you wish. Che ckpoints c reated wit h this fun ction from the pre-i nstall rou tine are p re-install checkpoin ts; checkp oints crea ted during the post- install ro utine are post-insta ll checkpo ints.
	7092	You can us e $$NEWCP^ XPDUTL to create a c heckpoint with or wi thout a ca llback. Yo u can also store a v alue for t he paramet er node, i f you wish .
	7093	Checkpoint s created with callb acks have that callb ack automa tically ex ecuted by KIDS durin g the appr opriate ph ase of the installat ion. If th e checkpoi nt is crea ted during the pre-i nstall rou tine, KIDS executes the callba ck as soon as the pr e-install routine co mpletes. I f the call back is cr eated duri ng the pos t-install, KIDS exec utes the c allback as soon as t he post-in stall rout ine comple tes. If mu ltiple che ckpoints a re created during th e pre- or post-insta ll routine , KIDS exe cutes the callbacks (and compl etes the c heckpoints ) in the o rder the c orrespondi ng checkpo ints were created.
	7094	Checkpoint s created without a callback c annot be e xecuted by KIDS; ins tead, they provide a way for d evelopers to store a nd retriev e informat ion during the pre-i nstall and post-inst all phases . Rather t han storin g informat ion in a l ocal or gl obal varia ble, you c an store i nformation in a chec kpoint par ameter nod e and retr ieve it (e ven if an installati on is re-s tarted).
	7095	If the che ckpoint yo u are tryi ng to crea te already exists, t he origina l paramete r and call back is no t overwrit ten.
	7096	Format:$$N EWCP^XPDUT L(name[,ca llback][,p ar_value])
	7097	Input Para meters:nam e:(require d) Checkpo int name.
	7098	callback:( optional) Callback ( ^routine o r tag^rout ine refere nce).
	7099	par_value: (optional) Value to which the checkpoint parameter is set.
	7100	Output:ret urns:Retur ns:
	7101	Internal E ntry Numbe r (IEN)—Cr eated chec kpoint if newly crea ted or if checkpoint already e xists.
	7102	Zero (0)—E rror occur red while creating c heckpoint.
	7103
	7104	$$OPTDE^XP DUTL(): Di sable/Enab le an Opti on
	7105	Reference Type:Suppo rted
	7106	Category:K IDS
	7107	ICR #:1014 1
	7108	Descriptio n:During K IDS instal lations—in Pre- or P ost-Init r outines, t his extrin sic functi on disable s or enabl es an opti on.
	7109	Format:$$O PTDE^XPDUT L(name,act ion)
	7110	Input Para meters:nam e:(require d) Option name.
	7111	action:(re quired) Se t to:
	7112	1—Enable a n option.
	7113	0—Disable an option.
	7114	Output:ret urns:Retur ns:
	7115	1—Success.
	7116	0—Failure.
	7117
	7118	Example
	7119	>I $$OPTDE ^XPDUTL(“X MUSER”,0) W !,’Optio n Disabled .’
	7120
	7121	$$PARCP^XP DUTL(): Ge t Checkpoi nt Paramet er
	7122	Reference Type:Suppo rted
	7123	Category:K IDS
	7124	ICR #:1014 1
	7125	Descriptio n:During K IDS instal lations, t his extrin sic functi on retriev es the cur rent value of a chec kpoint’s s tored para meter. The parameter is stored in the IN STALL file (#9.7).
	7126	Use this A PI for che ckpoints b oth with a nd without callbacks .
	7127	Use the op tional sec ond parame ter to ret rieve a pr e-install checkpoint ’s paramet er during a post-ins tall.
	7128	Format:$$P ARCP^XPDUT L(name[,pr e])
	7129	Input Para meters:nam e:(require d) Checkpo int name.
	7130	pre:(optio nal) To re trieve a p arameter f rom a pre- install ch eckpoint w hile in th e post-ins tall, set this param eter to “P RE”.
	7131	Output:ret urns:Retur ns the cur rent param eter node for the ch eckpoint n amed in th e name inp ut paramet er.
	7132
	7133	$$PATCH^XP DUTL(): Ve rify Patch Installat ion
	7134	Reference Type:Suppo rted
	7135	Category:K IDS
	7136	ICR #:1014 1
	7137	Descriptio n:During K IDS instal lations—du ring the e nvironment check onl y, this ex trinsic fu nction ver ifies if a patch has been inst alled. You can check for patch es with or without s equence nu mbers.
	7138	Format:$$P ATCH^XPDUT L(patch)
	7139	Input Para meters:pat ch:(requir ed) Patch name. Patc h name mus t include the full v ersion num ber with t he decimal point, su ch as XU8 .028.
	7140	Output:ret urns:Retur ns:
	7141	1—Specifie d patch wa s installe d on the c urrent sys tem.
	7142	0—Specifie d patch wa s not inst alled on t he current system.
	7143
	7144	Example
	7145	Checking f or a patch installat ion. Enter the follo wing at th e programm er prompt:
	7146
	7147	>I ‘$$PATC H^XPDUTL(“ XU8.028” ) W !,“You must inst all patch XU828”
	7148
	7149	$$PKG^XPDU TL(): Pars e Software Name from Build Nam e
	7150	Reference Type:Suppo rted
	7151	Category:K IDS
	7152	ICR #:1014 1
	7153	Descriptio n:This ext rinsic fun ction pars es the nam e of a sof tware appl ication fr om a softw are applic ation’s bu ild name. You can ob tain the n ame of the build KID S is insta lling from the KIDS key variab le XPDNM, which is d efined thr oughout a KIDS insta llation.
	7154	Format:$$P KG^XPDUTL( buildname)
	7155	Input Para meters:bui ldname:Nam e of build (.01 fiel d of BUILD file [#9. 6]).
	7156	Output:ret urns:Retur ns the sof tware name .
	7157
	7158	$$PRODE^XP DUTL(): Di sable/Enab le a Proto col
	7159	Reference Type:Suppo rted
	7160	Category:K IDS
	7161	ICR #:1014 1
	7162	Descriptio n:During K IDS instal lations—in Pre-Init or Post-In it routine s, this ex trinsic fu nction dis ables or e nables a p rotocol.
	7163	Format:$$P RODE^XPDUT L(name,act ion)
	7164	Input Para meters:nam e:(require d) Protoco l name.
	7165	action:(re quired) En ter one of the follo wing value s for this parameter :
	7166	1—Enable a protocol.
	7167	2—Disable a protocol .
	7168	Output:ret urns:Retur ns:
	7169	1—Success.
	7170	0—Failure.
	7171
	7172	$$RTNUP^XP DUTL(): Up date Routi ne Action
	7173	Reference Type:Suppo rted
	7174	Category:K IDS
	7175	ICR #:1014 1
	7176	Descriptio n:During K IDS instal lations—du ring the e nvironment check onl y, this ex trinsic fu nction upd ates the i nstallatio n action f or a routi ne.
	7177	Format:$$R TNUP^XPDUT L(routine, action)
	7178	Input Para meters:rou tine:(requ ired) Rout ine name.
	7179	action:(re quired) En ter one of the follo wing value s for this parameter :
	7180	1—Delete a t site.
	7181	2—Skip ins talling at site.
	7182	Output:ret urns:Retur ns:
	7183	1—Routine found in r outine ins tallation list.
	7184	0—Routine not found in routine installat ion list.
	7185
	7186	$$UPCP^XPD UTL(): Upd ate Checkp oint
	7187	Reference Type:Suppo rted
	7188	Category:K IDS
	7189	ICR #:1014 1
	7190	Descriptio n:During K IDS instal lations, t his extrin sic functi on updates the param eter node of an exis ting check point, in pre- or po st-install routines. The param eter node is stored in the INS TALL file (#9.7).
	7191	Use this A PI for che ckpoints b oth with a nd without callbacks .
	7192	During the pre-insta ll, you ca n only upd ate pre-in stall chec kpoints; d uring the post-insta ll, you ca n only upd ate post-i nstall che ckpoints.
	7193	Format:$$U PCP^XPDUTL (name[,par _value])
	7194	Input Para meters:nam e:(require d) Checkpo int name.
	7195	par_value: (optional) Sets chec kpoint par ameter to this value .
	7196	Output:ret urns:Retur ns:
	7197	Internal E ntry Numbe r (IEN)—Su ccessfully updated c heckpoint.
	7198	Zero (0)—E rror updat ing checkp oint.
	7199
	7200	$$VER^XPDU TL(): Pars e Version from Build Name
	7201	Reference Type:Suppo rted
	7202	Category:K IDS
	7203	ICR #:1014 1
	7204	Descriptio n:This ext rinsic fun ction pars es the ver sion of a software a pplication from a so ftware app lication’s build nam e. You can obtain th e name of the build KIDS is in stalling f rom the KI DS key var iable XPDN M, which i s defined throughout a KIDS in stallation .
	7205	Format:$$V ER^XPDUTL( buildname)
	7206	Input Para meters:bui ldname:(re quired) Na me of buil d (.01 fie ld of BUIL D file [#9 .6]).
	7207	Output:ret urns:Retur ns:
	7208	Version—Th e version of the bui ld identif ied in the buildname input par ameter.
	7209	NULL—If no match in the BUILD file (#9.6 ).
	7210
	7211	$$VERCP^XP DUTL(): Ve rify Check point
	7212	Reference Type:Suppo rted
	7213	Category:K IDS
	7214	ICR #:1014 1
	7215	Descriptio n:During K IDS instal lations, t his extrin sic functi on checks whether a given chec kpoint exi sts and, i f it exist s, whether it has co mpleted or not.
	7216	Use this A PI only fo r checkpoi nts with n o callback .
	7217	During the pre-insta ll, you ca n only ver ify pre-in stall chec kpoints; d uring the post-insta ll, you ca n only ver ify post-i nstall che ckpoints.
	7218	Format:$$V ERCP^XPDUT L(name)
	7219	Input Para meters:nam e:(require d) Checkpo int name.
	7220	Output:ret urns:Retur ns:
	7221	1—Checkpoi nt has com pleted.
	7222	0—Checkpoi nt has not completed but exist s.
	7223	-1—Checkpo int does n ot exist.
	7224
	7225	$$VERSION^ XPDUTL(): Package Fi le Current Version
	7226	Reference Type:Suppo rted
	7227	Category:K IDS
	7228	ICR #:1014 1
	7229	Descriptio n:This ext rinsic fun ction obta ins the cu rrent vers ion of a s ite’s soft ware appli cation.
	7230	Format:$$V ERSION^XPD UTL(packag e_id)
	7231	Input Para meters:pac kage_id:(r equired) S oftware ap plication’ s name or namespace, from its entry in t he PACKAGE file (#9. 4).
	7232	Output:ret urns:Retur ns:
	7233	Version—Th e current version of the softw are applic ation at t he site, a ccording t o the soft ware appli cation’s e ntry in th e site’s P ACKAGE fil e (#9.4).
	7234	NULL—If th e software applicati on is not matched.
	7235
	7236
	7237	Lock Manag er: Develo per Tools
	7238	Applicatio n Programm ing Interf ace (API)— Housekeepi ng
	7239	When an ap plication terminates , there ma y be house keeping re quired. A prime exam ple is the need to d elete temp orary data kept in t he ^TMP an d ^XTMP gl obals. An applicatio n that is terminated by the Lo ck Manager does not have the o pportunity to do its own house cleaning, but the Lo ck Manager can do it for the a pplication if it reg isters a h ousecleani ng routine via the A PI describ ed below.
	7240	CLEANUP^XU LMU(): Exe cute the H ousecleani ng Stack
	7241	Reference Type:Suppo rted
	7242	Category:L ock Manage r
	7243	ICR #:5832
	7244	Descriptio n:This API executes the housec leaning st ack set by the proce ss identif ied by DOL LARJ. Entr ies are ex ecuted in the first- in-first-o ut (FIFO) order, wit h the last entry add ed being t he first t o be execu ted, and L AST being the last e ntry execu ted. If th e LAST par ameter is not passed in, then the entire stack is executed.
	7245	NOTE: This API was r eleased wi th Kernel patch XU8 .0608.
	7246	Format:CLE ANUP^XULMU ([last])
	7247	Input Para meters:las t:(optiona l) This is the last entry that is execut ed. If not passed in , then the entire ho usecleanin g stack is executed.
	7248	Output:non e.
	7249
	7250	Examples
	7251	Example 1
	7252	An applica tion may e xecute the entire ho usecleanin g stack wi th the fol lowing cod e:
	7253	DO CLEANUP ^XULMU
	7254	Example 2
	7255	If an appl ication is called by another a pplication , then the first app lication m ay have al ready plac ed entries of its ow n on the s tack. So, the parame ter LAST n eeds to be passed, w ith LAST b eing the f irst entry placed on the stack . It is th e last ent ry execute d, since t hat stack is execute d in FIFO order.
	7256	DO CLEANUP ^XULM(last )
	7257	SETCLEAN^X ULMU(): Re gister a C leanup Rou tine
	7258	Reference Type:Suppo rted
	7259	Category:L ock Manage r
	7260	ICR #:5832
	7261	Descriptio n:This API registers a cleanup routine t hat should be execut ed when th e process is termina ted by the Kernel Lo ck Manager . An entry is create d on a sta ck kept fo r the proc ess. The l ocation is ^XTMP(“XU LM CLEANUP _”_$J), wh ere $J uni quely iden tifies the process. A process can call S ETCLEAN^XU LMU repeat edly, and each time a new entr y is place d on the s tack.
	7262	CAUTION: O nce an app lication c alls SETCL EAN, upon exiting it must eith er execute its house cleaning s tack or de lete it us ing the AP Is CLEAN o r UNCLEAN.
	7263	NOTE: This API was r eleased wi th Kernel patch XU8 .0608.
	7264	Format:SET CLEAN^XULM U(rtn,.var )
	7265	Input Para meters:rtn :(required ) The rout ine to be executed w hen the pr ocess is t erminated.
	7266	.var:(requ ired) An i nput array containin g a list o f variable s that sho uld be def ined when the routin e is execu ted. It is up to the applicati on to ensu re that al l the requ ired varia bles are d efined whe n CLEAN^XU LMU is cal led.
	7267	Output:ret urns:Retur ns an inte ger that i dentifies the entry created on the stack . The appl ication ne eds to ret ain the va lue in ord er to exec ute the en try on the houseclea ning stack or remove it.
	7268
	7269	Example
	7270	Suppose th e applicat ion has a cleanup ro utine CLEA NUP^XXAPP, and it ne eds to be executed w ith DFN de fined with its prese nt valued. The appli cation wou ld use thi s API as f ollows:
	7271	N VAR,CLEA NUP
	7272	S VAR(“DFN ”)=DFN
	7273	S CLEANUP= $$SETCLEAN ^XULMU(“CL EANUP^XXAP P”,.VAR)
	7274	The applic ation’s ho usekeeping stack wou ld look li ke this:
	7275	^XTMP(“XUL M CLEANUP” ,$J,1,“ROU TINE”)=“CL EANUP^XXAP P”
	7276	^XTMP(“XUL M CLEANUP” ,$J,1,“VAR IABLES”,”D FN”)=10000 61
	7277	UNCLEAN^XU LMU(): Rem ove Entrie s from the Houseclea ning Stack
	7278	Reference Type:Suppo rted
	7279	Category:L ock Manage r
	7280	ICR #:5832
	7281	Descriptio n:This API removes e ntries fro m the hous ecleaning stack set by calling the SETCL EAN^XULMU( ): Registe r a Cleanu p Routine API. Entri es are rem oved in Fi rst-In-Fir st-Out (FI FO) order. If the LA ST paramet er is not passed in, then the entire sta ck is dele ted; other wise, just the entri es back to LAST are removed.
	7282	NOTE: This API was r eleased wi th Kernel patch XU8 .0608.
	7283	Format:UNC LEAN^XULMU ([last])
	7284	Input Para meters:las t:(optiona l) Identif ies the la st entry o n the hous ekeeping s tack to re move. Entr ies are re moved in F IFO order. Therefore , the firs t entry re moved is t he last en try that w as added, and the la st entry r emoved is LAST. If n ot passed in, the en tire house cleaning s tack is de leted.
	7285	Output:non e.
	7286
	7287	Examples
	7288	Example 1
	7289	This examp le would r emove the entire hou secleaning stack:
	7290	DO UNCLEAN ^XULMU
	7291	Example 2
	7292	If an appl ication is called by another a pplication , then the first app lication m ay have al ready plac ed entries of its ow n on the s tack. So, the parame ter LAST n eeds to be passed, w ith LAST b eing the f irst entry placed on the stack . It is th e last ent ry deleted , since th at stack i s executed in first- in-first-o ut (FIFO) order.
	7293	DO UNCLEAN ^XULMU(las t)
	7294	Applicatio n Programm ing Interf ace (API)— Lock Dicti onary
	7295	ADDPAT^XUL MU(): Add Patient Id entifiers for a Comp utable Fil e Referenc e
	7296	Reference Type:Suppo rted
	7297	Category:L ock Manage r
	7298	ICR #:5832
	7299	Descriptio n:This API is very s imilar to the PAT^XU LMU(): Get a Standar d Set of P atient Ide ntifiers A PI, except that it i s used to add the pa tient iden tifiers fo r a comput able file reference for a file that is n ot the PAT IENT file (#2). The computable file refe rences can include a dditional identifier s. For exa mple, a co mputable f ile refere nce for a billing fi le can con tain the b ill number as an ide ntifier as well as t he patient identifie rs returne d by the A DDPAT^XULM U API.
	7300	NOTE: This API was r eleased wi th Kernel patch XU8 .0608.
	7301	Format:ADD PAT^XULMU( dfn)
	7302	Input Para meters:dfn :(required ) The IEN of a recor d in the P ATIENT fil e (#2).
	7303	Output:ret urns:Retur ns ID(0): If not def ined at th e point th e ADDPAT^X ULMU API i s called, it is init ially set to 0. When the ADDPA T^XULMU AP I returns, the ID(0) is increm ented by 4 .
	7304	ID(ID(0)+1 )=<patient name>
	7305	ID(ID(0)+2 )=<patient sex>
	7306	ID(ID(0)+3 )=<patient date of b irth>
	7307	ID(ID(0)+4 )=<patient Social Se curity Num ber>
	7308
	7309	PAT^XULMU( ): Get a S tandard Se t of Patie nt Identif iers
	7310	Reference Type:Suppo rted
	7311	Category:L ock Manage r
	7312	ICR #:5832
	7313	Descriptio n:This API is for us e within t he M code for a comp utable fil e referenc e to the P ATIENT fil e (#2). It returns a standard set of pat ient ident ifiers.
	7314	NOTE: This API was r eleased wi th Kernel patch XU8 .0608.
	7315	Format:PAT ^XULMU(dfn )
	7316	Input Para meters:dfn :(required ) The IEN of a recor d in the P ATIENT fil e (#2).
	7317	Output:ret urns:Retur ns the fol lowing var iables:
	7318	ID(“IEN”)= DFN
	7319	ID(0)=4
	7320	ID(1)=<pat ient name>
	7321	ID(2)=<pat ient sex>
	7322	ID(3)=<pat ient date of birth>
	7323	ID(4)=<pat ient Socia l Security Number>
	7324
	7325	Example
	7326	Assuming t hat DFN is a variabl e defined within the Lock temp late, then the M cod e for a co mputable f ile refere nce to the PATIENT f ile (#2) w ould consi st of the following:
	7327	DO PAT^XUL MU(DFN)
	7328
	7329
	7330	Menu Manag er: Develo per Tools
	7331	Creating O ptions
	7332	You can de velop appl ications q uickly and easily us ing Menu M anager. On ce you hav e defined a set of f iles using VA FileMa n, you can use Menu Manager to provide a menu of o ptions inc luding ent ering, edi ting, disp laying, an d printing informati on. You ca n use M co de to tail or the fun ctioning o f an optio n, in the option’s h eader, ent ry, or exi t action. You can cr eate speci alized rou tine-type options. A nd you can associate help fram es with op tions (as described in the Hel p Processo r section) to furthe r enhance option cre ation and custom tai loring.
	7333	Option Typ es
	7334	Several di fferent op tion types exist:
	7335	Edit, Inqu ire, and P rint are m ainly used to access VA FileMa n files.
	7336	Action and Run Routi ne types a re availab le for inv oking M co de.
	7337	Menu types , as discu ssed earli er in this section, are used t o group ot her option s for pres entation t o the user at the se lect promp t.
	7338	Server opt ions are o ptions tha t can be a ddressed t hrough Mai lMan (send ing to S.S ERVER NAME ). The ser ver activi ty, such a s the runn ing of a r outine, is then carr ied out.
	7339	REF: For a complete descriptio n, see the “Server O ptions: De veloper To ols” secti on in this section.
	7340	Protocol, Protocol M enu, Exten ded Action , and Limi ted option types are specific to the XQO R (Unwinde r) softwar e applicat ion. Contr ol is pass ed to the XQOR (Unwi nder) soft ware for p rocessing. The Exten ded Action type, for example, “unwinds” the items on a menu in a speci fic order. Protocol Menus are formatted in multipl e columns allowing s everal ite ms to be s elected at once. The Protocol- type optio n prompts the user f or a selec tion. Limi ted protoc ols involv e patient- oriented p rocessing, rather th an applica tion-speci fic tasks. Any of th ese option types are included, like othe r options, when a so ftware app lication i s exported .
	7341	REF: For m ore inform ation, see the Compu terized Pa tient Reco rd System (CPRS) or Unwinder ( XQOR) docu mentation.
	7342	Creating O ptions (Ed it Options )
	7343	Figure 78: Menu Mana ger—Edit o ptions [XU EDITOPT]
	7344	MENU MANAG EMENT...[X UMAINT]
	7345	Edit op tions[XUED ITOPT]
	7346
	7347	You can de fine optio ns with th e Edit Opt ions templ ate, avail able from the Menu M anagement menu. Depe nding on w hat type o f option y ou are edi ting, the Edit Optio ns templat e branches to the fi elds in th e OPTION f ile (#19) appropriat e for that option ty pe.
	7348	Some optio n types (E dit, Inqui re, and Pr int) have fields who se names c orrespond to VA File Man DI var iables. Th e Edit Opt ions templ ate branch es to the DI fields that have relevance to the typ e of VA Fi leMan call being mad e by the o ption.
	7349	For Edit t ype option s, the DI fields pre sented cor respond to the input variables for an ^D IE call. L ikewise, i nquire-typ e options correspond to ^DIQ c alls, and print opti ons to ^DI P calls.
	7350	REF: For a complete descriptio n of the m eaning of the variab les repres ented by e ach of the DI fields , see the VA FileMan Developer ’s Guide.
	7351	Options th at Should Be Regular ly Schedul ed
	7352	If an opti on should be regular ly schedul ed to run through Ta skMan, you should se t its SCHE DULING REC OMMENDED f ield (#209 ) in the O PTION file (#19)) to YES. Site s are not able to us e Schedule /Unschedul e Options to schedul e an optio n unless t his field is set to YES for th e option.
	7353	Variables for Develo per Use
	7354	The appear ance and f unctioning of the me nu system can be mod ified by d evelopers by using s everal var iables. Th e variable s can be d efined wit hin applic ations, su ch as in a n option’s Entry Act ion, Exit Action, or Header. T hese varia bles are l isted belo w.
	7355	The XQMM v ariables c an be used individua lly or tog ether. It is strongl y recommen ded that y ou test th e effects of XQMM va riables wi th the AUT O MENU dis play, DUZ( “AUTO”), t urned on a nd off.
	7356	XQUIT: Qui t the Opti on
	7357	This varia ble can be set in an option’s Entry Acti on to caus e Menu Man ager to qu it and not invoke th e option. The menu s ystem does not run t he option, either as a foregro und job or backgroun d task, an d does not jump past the optio n. If an o ption’s us e depends on the exi stence of certain ap plication- specific k ey variabl es, for ex ample, the Entry Act ion logic can set XQ UIT if tho se variabl es are not defined. Menu Manag er simply checks for the exist ence of th e XQUIT va riable, so it can be set to NU LL (S XQUI T=“”) or t o a value as the dev eloper cho oses.
	7358	XQMM(“A”): Menu Prom pt
	7359	If XQMM(“A ”) exists, the menu system use s it as th e prompt i nstead of the normal “Select.. .option” m enu prompt . This var iable is K ILLed imme diately af ter it is used. It d oes not in hibit the AUTO MENU display. I f the user has chose n to have options di splayed at each cycl e of the m enu system , then the options a re display ed before the XQMM(“ A”) prompt is presen ted. Unlik e the phan tom jump, prompts mu st be set singularly , and cann ot be conc atenated w ith a semi colon.
	7360	XQMM(“B”): Default R esponse
	7361	If XQMM(“B ”) is defi ned, the m enu system uses it a s the defa ult respon se and is presented along with the usual two slash es (“//”). If the us er accepts the defau lt by pres sing <Ente r>, the de fault beco mes the us er’s respo nse.
	7362	XQMM(“B”) identifies an option if set to a unique synonym or a unique string of text from the beginn ing of the option’s menu text. This opti on must ex ist on the user’s cu rrent menu . If the o ption cann ot be foun d, Menu Ma nager resp onds with two questi on marks ( “??”), KIL L both XQM M(“A”) and XQMM(“B”) , and disp lay the st andard men u prompt.
	7363	XQMM(“J”): The Phant om Jump
	7364	This varia ble can be used to f orce a men u jump to an option within the user’s me nu tree. S et it equa l to the e xact optio n name (i. e., .01 fi eld of the OPTION fi le [#19]) to which M enu Manage r should j ump. For e xample:
	7365	>S XQMM(“J ”)=“XUMAIN T”
	7366	This jumps to the Me nu Managem ent option if that o ption is w ithin the user’s men u tree.
	7367	The phanto m jump aut omatically turns off the user’ s menu dis play for o ne cycle t hrough the menu syst em so that the user does not s ee a list of choices before ju mping to a n option t hat is not on that l ist.
	7368	The phanto m jump can also be u sed to des ignate a s et of opti ons for a series of jumps, cal led a scri pt. The ex act option names sho uld be sep arated wit h semicolo ns. For ex ample:
	7369	>S XQMM(“J ”)=“XUMAIN T;DIUSER”
	7370	After jump ing to Men u Manageme nt, the me nu system would jump to VA Fil eMan (prov ided that all of the access an d security requireme nts are me t).
	7371	After all the option s in a scr ipt have b een comple ted, the p hantom jum p logic re turns the user to th e option t hat was la st run bef ore the sc ript was i nvoked. If for some reason thi s cannot b e accompli shed, the user is re turned to their prim ary menu.
	7372	XQMM(“N”): No Menu D isplay
	7373	This varia ble can be used to s uppress th e AUTO MEN U display of menu op tions for one menu c ycle. XQMM (“N”) is t hen KILLed and the d isplay res umes as us ual. XQMM( “N”) can b e used in conjunctio n with XQM M(“A”) and (“B”) to present on ly the cus tom tailor ed menu pr ompts.
	7374	Setting XQ MM(“N”) do es not cha nge the di splay for users who already su ppress the AUTO MENU display. For users who have A UTO MENU t urned on, XQMM(“N”) takes prec edence ove r DUZ(“AUT O”).
	7375	It is not necessary to define XQMM(“N”) when using the phant om jump, X QMM(“J”), since the display is already s uppressed. If XQMM(“ J”) is pre sent, then XQMM(“N”) is not KI LLed after the first cycle sin ce the pha ntom jump is already inhibitin g the disp lay. In th is case, X QMM(“N”) i s KILLed a fter the s econd cycl e (the dis play of me nus after the jump i s complete d). If sev eral phant om jumps a re chained together, XQMM(“N”) is not KI LLed until one cycle after the final jum p unless c ode is add ed to expl icitly KIL L it betwe en jumps.
	7376	Direct Mod e Utilitie s
	7377	Several Me nu Manager direct mo de utiliti es are ava ilable for developer s to use a t the M pr ompt. They are not A PIs and ca nnot be us ed in soft ware appli cation rou tines. The se direct mode utili ties are d escribed b elow.
	7378	^XQ1: Test an Option
	7379	The ^XQ1 r outine ask s you to s elect an o ption; it then uses the select ed option as the pri mary menu option for entry int o the menu system (a t the top of ^XQ). T his provid es a way f or an indi vidual in Programmer mode to e nter into the menu s ystem at a desired o ption:
	7380	>D ^XQ1
	7381	This API i s also cal led by ^XU P.
	7382	CAUTION: D evelopers are advise d to use ^ XUP instea d of ^XQ1 to enter K ernel from Programme r mode, si nce the ^X UP routine sets up a standard environmen t and take s care of cleanup ac tivities.
	7383	REF: For a descripti on of the ^XUP direc t mode uti lity, see the “Signo n/Security : Develope r Tools” s ection.
	7384	NOTE: Whil e D ^XQ1 i s a direct mode util ity, it is not a cal lable API.
	7385	Applicatio n Programm ing Interf ace (API)
	7386	Several AP Is are ava ilable for developer s to work with menu management . These AP Is are des cribed bel ow.
	7387	$$ADD^XPDM ENU(): Add Option to Menu
	7388	Reference Type:Suppo rted
	7389	Category:M enu Manage r
	7390	ICR #:1157
	7391	Descriptio n:This ext rinsic fun ction adds an option as a new item to an existing menu.
	7392	Format:$$A DD^XPDMENU (menu,opti on[,syn][, order])
	7393	Input Para meters:men u:(require d) Name of the menu to which a n option s hould be a dded.
	7394	option:(re quired) Na me of the option bei ng added t o the menu .
	7395	syn:(optio nal) Synon ym to add to the SYN ONYM field in the ne w menu ite m.
	7396	order:(opt ional) Ord er to plac e in the D ISPLAY ORD ER field i n the new menu item.
	7397	Output:ret urns:Retur ns:
	7398	1—Success, option ad ded to men u.
	7399	0—Failure, option no t added to menu.
	7400
	7401	$$DELETE^X PDMENU(): Delete Men u Item
	7402	Reference Type:Suppo rted
	7403	Category:M enu Manage r
	7404	ICR #:1157
	7405	Descriptio n:This ext rinsic fun ction dele tes an opt ion from t he Menu fi eld of ano ther optio n. It retu rns the fo llowing va lues:
	7406	1—If the f unction su cceeded.
	7407	0—If it fa iled.
	7408	Format:$$D ELETE^XPDM ENU(menu,o ption)
	7409	Input Para meters:men u:(require d) This is the name of the opt ion from w hich you w ant to del ete a menu item.
	7410	option:(re quired) Th is is the name of th e option y ou want to delete fr om the men u item of the “menu” input par ameter.
	7411	Output:ret urns:Retur ns:
	7412	1—Success, menu item deleted.
	7413	0—Failure, menu item not delet ed.
	7414
	7415	$$LKOPT^XP DMENU(): L ook Up Opt ion IEN
	7416	Reference Type:Suppo rted
	7417	Category:M enu Manage r
	7418	ICR #:1157
	7419	Descriptio n:This ext rinsic fun ction look s up an op tion’s Int ernal Entr y Number ( IEN) using the “B” c ross-refer ence.
	7420	Format:$$L KOPT^XPDME NU(option)
	7421	Input Para meters:opt ion:(requi red) The n ame of the option.
	7422	Output:ret urns:Retur ns the Int ernal Entr y Number ( IEN) of th e input op tion in th e OPTION f ile (#19).
	7423
	7424	OUT^XPDMEN U(): Edit Option’s O ut of Orde r Message
	7425	Reference Type:Suppo rted
	7426	Category:M enu Manage r
	7427	ICR #:1157
	7428	Descriptio n:This API creates o r deletes an out of order mess age for an option; t his action effective ly puts th e option o ut of orde r or back in order.
	7429	Format:OUT ^XPDMENU(o ption,text )
	7430	Input Para meters:opt ion:(requi red) Name of option in which t o place an OUT OF OR DER MESSAG E value.
	7431	text:(requ ired) Text of messag e to place in the op tion’s OUT OF ORDER MESSAGE fi eld.
	7432	If this is not NULL, the text is stored in the opt ion’s OUT OF ORDER M ESSAGE fie ld and the option is placed ou t of order .
	7433	If this pa rameter is passed as a NULL st ring, the current OU T OF ORDER MESSAGE v alue is de leted, and the optio n is put b ack in ord er.
	7434	Output:non e.
	7435
	7436	RENAME^XPD MENU(): Re name Optio n
	7437	Reference Type:Suppo rted
	7438	Category:M enu Manage r
	7439	ICR #:1157
	7440	Descriptio n:This API renames a n existing option.
	7441	Format:REN AME^XPDMEN U(old,new)
	7442	Input Para meters:old :(required ) Current option nam e (.01 fie ld of OPTI ON file [# 19] entry) . Must be an exact m atch.
	7443	new:(requi red) New n ame for op tion.
	7444	Output:non e.
	7445
	7446	$$TYPE^XPD MENU(): Ge t Option T ype
	7447	Reference Type:Suppo rted
	7448	Category:M enu Manage r
	7449	ICR #:1157
	7450	Descriptio n:This ext rinsic fun ction retu rns the op tion’s TYP E field (# 4) in the OPTION fil e (#19).
	7451	Format:$$T YPE^XPDMEN U(option)
	7452	Input Para meters:opt ion:(requi red) The n ame of the option.
	7453	Output:ret urns:Retur ns the one character TYPE fiel d (#4) val ue of the input opti on in the OPTION fil e (#19). F or example :
	7454	A—Action
	7455	E—Edit
	7456	I—Inquire
	7457	M—Menu
	7458	P—Print
	7459	R—Run rout ine
	7460	O—Protocol
	7461	Q—Protocol Menu
	7462	X—Extended Action
	7463	S—Server
	7464	L—Limited
	7465	C—ScreenMa n
	7466	W—Window
	7467	Z—Window S uite
	7468	B—Broker ( Client/Ser ver)
	7469	$$ADD^XPDP ROT(): Add Child Pro tocol to P arent Prot ocol
	7470	Reference Type:Suppo rted
	7471	Category:M enu Manage r
	7472	ICR #:5567
	7473	Descriptio n:This ext rinsic fun ction adds a CHILD p rotocol to a PARENT protocol I TEM multip le (#10) i n the PROT OCOL file (#101).
	7474	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7475	Format:$$A DD^XPDPROT (parent,ch ild[,mnemo nic][,sequ ence])
	7476	Input Para meters:par ent:(requi red) Name of the PAR ENT protoc ol in the PROTOCOL f ile (#101) to which a CHILD pr otocol sho uld be add ed.
	7477	child:(req uired) Nam e of the C HILD proto col being added to t he PARENT protocol i n the PROT OCOL file (#101).
	7478	mnemonic:( optional) The mnemon ic value t o be added to the MN EMONIC fie ld (#2) in the ITEM multiple ( #10) in th e PROTOCOL file (#10 1) for the CHILD in the PARENT protocol.
	7479	sequence:( optional) The sequen ce value t o be added to the SE QUENCE fie ld (#3) in the ITEM multiple ( #10) in th e PROTOCOL file (#10 1) for the CHILD in the PARENT protocol.
	7480	Output:ret urns:Retur ns:
	7481	1—Success, CHILD pro tocol adde d to the i nput PAREN T protocol ITEM mult iple (#10) in the PR OTOCOL fil e (#101).
	7482	0—Failure, CHILD pro tocol not added to t he input P ARENT prot ocol ITEM multiple ( #10) in th e PROTOCOL file (#10 1).
	7483
	7484	$$DELETE^X PDPROT(): Delete Chi ld Protoco l from Par ent Protoc ol
	7485	Reference Type:Suppo rted
	7486	Category:M enu Manage r
	7487	ICR #:5567
	7488	Descriptio n:This ext rinsic fun ction dele tes a CHIL D protocol from a PA RENT proto col ITEM m ultiple (# 10) in the PROTOCOL file (#101 ).
	7489	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7490	Format:$$D ELETE^XPDP ROT(parent ,child)
	7491	Input Para meters:par ent:(requi red) Name of the PAR ENT protoc ol in the PROTOCOL f ile (#101) from whic h a CHILD protocol s hould be d eleted.
	7492	child:(req uired) Nam e of the C HILD proto col being deleted fr om the PAR ENT protoc ol in the PROTOCOL f ile (#101) .
	7493	Output:ret urns:Retur ns:
	7494	1—Success: CHILD pro tocol dele ted from t he input P ARENT prot ocol ITEM multiple ( #10) in th e PROTOCOL file (#10 1).
	7495	0—Failure: CHILD pro tocol not deleted fr om the inp ut PARENT protocol I TEM multip le (#10) i n the PROT OCOL file (#101).
	7496
	7497	FIND^XPDPR OT(): Find All Paren ts for a P rotocol
	7498	Reference Type:Suppo rted
	7499	Category:M enu Manage r
	7500	ICR #:5567
	7501	Descriptio n:This API finds all parents f or a proto col in the PROTOCOL file (#101 ) and retu rns the li st in the RESULT arr ay:
	7502	RESULT(0)= Number of parents fo und or -1^ error mess age.
	7503	RESULT(ien )=Protocol name.
	7504	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7505	Format:FIN D^XPDPROT( .result,pr otocol)
	7506	Input Para meters:.re sult:(requ ired) The array to r eturn the results, p assed by r eference:
	7507	RESULT(0)= Number of parents fo und or -1^ error mess age.
	7508	RESULT(ien )=Protocol name.
	7509	protocol:( required) Name of th e protocol in the PR OTOCOL fil e (#101) f or which t o find the parents.
	7510	Output:ret urns:Retur ns the RES ULT array:
	7511	RESULT(0)= Number of parents fo und or -1^ error mess age.
	7512	RESULT(ien )=Protocol name
	7513
	7514	$$LKPROT^X PDPROT(): Look Up Pr otocol IEN
	7515	Reference Type:Suppo rted
	7516	Category:M enu Manage r
	7517	ICR #:5567
	7518	Descriptio n:This ext rinsic fun ction retu rns the in ternal ent ry number (IEN) of t he input p rotocol fr om the PRO TOCOL file (#101).
	7519	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7520	Format:$$L KPROT^XPDP ROT(protoc ol)
	7521	Input Para meters:pro tocol:(req uired) Nam e of the p rotocol to look up i n the PROT OCOL file (#101).
	7522	Output:ret urns:Retur ns the int ernal entr y number ( IEN) of th e input pr otocol in the PROTOC OL file (# 101).
	7523
	7524	OUT^XPDPRO T(): Edit Protocol’s Out of Or der Messag e
	7525	Reference Type:Suppo rted
	7526	Category:M enu Manage r
	7527	ICR #:5567
	7528	Descriptio n:This API creates o r deletes an “Out of Order” me ssage in t he DISABLE field (#2 ) in the P ROTOCOL fi le (#101) for the in put protoc ol.
	7529	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7530	Format:OUT ^XPDPROT(p rotocol,te xt)
	7531	Input Para meters:pro tocol:(req uired) Nam e of the p rotocol in the PROTO COL file # 101) to wh ich the “O ut of Orde r” text is assigned.
	7532	text:(requ ired) Text value:
	7533	Text—Messa ge text to place in the DISABL E field (# 2) in the PROTOCOL f ile (#101) for the i nput proto col.
	7534	Null—Delet e any mess age text i n the DISA BLE field (#2) in th e PROTOCOL file (#10 1) for the input pro tocol.
	7535	Output:ret urns:Retur ns:
	7536	Text—Updat ed message text in t he DISABLE field (#2 ) in the P ROTOCOL fi le (#101) for the in put protoc ol. Markin g the prot ocol “Out of Order.”
	7537	Null—Delet ed message text in t he DISABLE field (#2 ) in the P ROTOCOL fi le (#101) for the in put protoc ol.
	7538
	7539	RENAME^XPD PROT(): Re name Proto col
	7540	Reference Type:Suppo rted
	7541	Category:M enu Manage r
	7542	ICR #:5567
	7543	Descriptio n:This API renames a n existing protocol name. It u pdates the value in the NAME f ield (#.01 ) in the P ROTOCOL fi le (#101).
	7544	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7545	Format:REN AME^XPDPRO T(old,new)
	7546	Input Para meters:old :(required ) Current (old) name of the pr otocol to be renamed in the PR OTOCOL fil e (#101).
	7547	new:(requi red) New n ame for th e protocol .
	7548	Output:ret urns:Retur ns the upd ated NAME field (#.0 1) in the PROTOCOL f ile (#101) .
	7549
	7550	$$TYPE^XPD PROT(): Ge t Protocol Type
	7551	Reference Type:Suppo rted
	7552	Category:M enu Manage r
	7553	ICR #:5567
	7554	Descriptio n:This ext rinsic fun ction retu rns the va lue of the TYPE fiel d (#4) in the PROTOC OL file (# 101) for t he input p rotocol IE N.
	7555	NOTE: This API was r eleased wi th Kernel patch XU8 .0547.
	7556	Format:$$T YPE^XPDPRO T(protocol _ien)
	7557	Input Para meters:pro tocol_ien: (required) The proto col’s inte rnal entry number (I EN) in the PROTOCOL file (#101 ).
	7558	Output:ret urns:Retur ns the one character TYPE fiel d (#4) val ue in the PROTOCOL f ile (#101) for the i nput proto col IEN. F or example :
	7559	A—Action: Same as th e “X” type , except a ny existin g sub-item s are not executed.
	7560	M—Menu: Us e this typ e for disp laying and selecting items.
	7561	O—Protocol : This val ue is stri ctly relat ed to the Add orders function. It is the same as t he “Q” typ e, except the protoc ol is the item selec ted. Proto cols are d irectly ex ecuted whe n encounte red.
	7562	Q—Protocol Menu: Thi s value is strictly related to the Add o rders func tion. Use it for dis playing an d selectin g orderabl e items du ring the a dd sequenc e. When th is type of protocol is encount ered OE/RR prompts t he user wi th “Select PATIENT:, ” “LOCATIO N:,” and “ Provider:, ” and exec ute the tr ansaction logic for the new or ders scree n.
	7563	L—Limited Protocol: This value is strict ly related to the Ad d orders f unction. I t is the s ame as the “O” type, except an y existing sub-items are not e xecuted.
	7564	X—Extended Action: P rotocols o f this typ e execute the entry action plu s all sub- items.
	7565	D—Dialog.
	7566	T—Term.
	7567	E—Event Dr iver.
	7568	S—Subscrib er.
	7569
	7570	NEXT^XQ92( ): Restric ted Times Check
	7571	Reference Type:Suppo rted
	7572	Category:M enu Manage r
	7573	ICR #:1007 7
	7574	Descriptio n:This API returns t he next ti me an opti on can run , checking any time or date re strictions placed on the optio n. If ther e are no t imes in th e next wee k when the option ca n be run, the x para meter is r eturned as NULL and a message is issued regarding the time r estriction .
	7575	Format:NEX T^XQ92(ien ,x)
	7576	Input Para meters:ien :(required ) Internal entry num ber (IEN) of the opt ion in the OPTION fi le (#19).
	7577	x:The date /time in V A FileMan format of the next u nrestricte d runtime when the o ption can run.
	7578	Output:x:R eturns the next time an option can run:
	7579	Current Ti me—If the option is able to ru n at the c urrent tim e.
	7580	Null—If th e option i s prohibit ed for the entire ne xt week. I t also iss ues a mess age regard ing the ti me restric tion.
	7581
	7582	$$ACCESS^X QCHK(): Us er Option Access Tes t
	7583	Reference Type:Suppo rted
	7584	Category:M enu Manage r
	7585	ICR #:1007 8
	7586	Descriptio n:This ext rinsic fun ction dete rmines if a user has access to a particu lar option .
	7587	Format:$$A CCESS^XQCH K(duz,opti on)
	7588	Input Para meters:duz :(required ) The iden tification number of the user in questio n in the N EW PERSON file (#200 ).
	7589	option:(re quired) Th e Internal Entry Num ber (IEN) or option name of th e option i n question in the OP TION file (#19).
	7590	Output:ret urns:Retur ns:
	7591	-1—No such user in t he NEW PER SON file ( #200).
	7592	-2—User te rminated o r has no A ccess code .
	7593	-3—No such option in the Optio n file (#1 9).
	7594	0—No acces s found in any menu tree the u ser owns.
	7595	4-Piece St ring:
	7596	access^men u tree IEN ^a set of codes^key
	7597	0^tree^cod es^key: No access be cause of l ocks (see XQCODES be low).
	7598	1^OpIEN^^: Access al lowed thro ugh Primar y Menu.
	7599	2^OpIEN^co des^: Acce ss found i n the Comm on Options .
	7600	3^OpIEN^co des^: Acce ss found i n top leve l of secon dary optio n.
	7601	4^OpIEN^co des^: Acce ss through the secon dary menu tree OpIEN .
	7602	XQCODES ca n contain the follow ing:
	7603	N—No Prima ry Menu in the NEW P ERSON file (#200, wa rning only ).
	7604	L—Locked a nd the use r does not have the key (force s zero [0] in first piece).
	7605	R—Reverse lock and u ser has th e key (for ces zero [ 0] in firs t piece).
	7606
	7607	OP^XQCHK() : Current Option Che ck
	7608	Reference Type:Suppo rted
	7609	Category:M enu Manage r
	7610	ICR #:1007 8
	7611	Descriptio n:This API returns t he current option or protocol name and m enu text i n the firs t and seco nd pieces of the XQO PT output variable. It looks f or the loc al XQORNOD if define d or the l ocal XQY v ariable; t he interna l number o f the opti on, if XQO RNOD is de fined, nee ds to be i n the vari able point er format:
	7612	XQORNOD=<i nternal nu mber of th e protocol >;<protoco l file>
	7613	If the sea rch is uns uccessful, because t he job is not runnin g out of t he menu sy stem or is not a tas ked option , XQOPT is returned with -1 in the first piece and “Unknown” in the se cond.
	7614	NOTE: XQCH K cannot r eturn opti on/protoco l informat ion if the job is a task that did not or iginate fr om an opti on.
	7615	Format:OP^ XQCHK
	7616	Make sure to perform the follo wing steps before ca lling this API:
	7617	NEW all no n-namespac ed variabl es.
	7618	Set all in put variab les.
	7619	Call the A PI.
	7620	Input Vari ables:XQOR NOD:(optio nal) If th is variabl e is defin ed, it sho uld be in variable p ointer for mat. For e xample:
	7621	XQORNOD=“1 234;ORD(10 1,”
	7622	Output Var iables:XQO PT:Returns a string in the fol lowing for mat:
	7623	Option/Pro tocol Name ^Menu Text
	7624	If neither an option nor a pro tocol can be identif ied, XQOPT is return ed as:
	7625	-1^Unknown
	7626
	7627	Examples
	7628	Example 1
	7629	>K XQORNOD D OP^XQCH K W !,XQOP T
	7630
	7631	>EVE^Syste ms Manager Menu
	7632
	7633	Example 2
	7634	>S XQORNOD =“445;ORD( 101,” D OP ^XQCHK W ! ,XQOPT
	7635
	7636	>XU USER E VENT TERMI NATE^Termi nate User Event
	7637
	7638	Example 3
	7639	>S XQORNOD =“9;DIC(19 ,” D OP^XQ CHK W !,XQ OPT
	7640
	7641	>EVE^Syste ms Manager Menu
	7642
	7643	Example 4
	7644	>K XQORNOD ,XQY,XQOPT D OP^XQCH K W !,XQOP T
	7645
	7646	>-1^Unknow n
	7647
	7648
	7649	Miscellane ous: Devel oper Tools
	7650	Direct Mod e Utilitie s
	7651	Several Ke rnel Toolk it direct mode utili ties are a vailable f or develop ers to use at the M prompt, us ually invo lving the DO command . They are not APIs and cannot be used i n software applicati on routine s.
	7652	Many of th e options on the Pro grammer Op tions menu can also be run as direct mod e utilitie s. Some ar e not avai lable as o ptions, bu t only as direct mod e utilitie s callable at the M prompt. Ta ble 28 lis ts example s on how t o run thes e utilitie s when wor king in Pr ogrammer m ode.
	7653	Table 28: Miscellane ous Tools— Direct Mod e Utilitie s
	7654	Direct Mod e Utility
	7655	Descriptio n
	7656	>D ^%G
	7657	List the c ontents of a global to the scr een.
	7658
	7659	Programmer Options M enu
	7660
	7661	Figure 79: Programme r Options menu optio ns—Toolkit miscellan eous tools
	7662	SYSTEMS MA NAGER MENU ...[EVE]
	7663	Programm er Options ... <lock ed with XU PROG>[XUPR OG]
	7664	KIDS Ke rnel Insta llation & Distributi on System ...[XPD MA IN]
	7665	<locked with XUPRO G>
	7666	PG Prog rammer mod e <locked with XUPRO GMODE>[XUP ROGMODE]
	7667	Calc ulate and Show Check sum Values [XTSUMBLD- CHECK]
	7668	Dele te Unrefer enced Opti ons[XQ UNR EF’D OPTIO NS]
	7669	Erro r Processi ng ...[XUE RRS]
	7670	Gene ral Parame ter Tools ...[XPAR M ENU TOOLS]
	7671	Glob al Block C ount[XU BL OCK COUNT]
	7672	List Global <l ocked with XUPROGMOD E>[XUPRGL]
	7673	Rout ine Tools ...[XUPR-R OUTINE-TOO LS]
	7674	Test an option not in yo ur menu <l ocked with XUMGR>[XT -OPTION TE ST]
	7675
	7676	Delete Unr eferenced Options
	7677	The Delete Unreferen ced Option s option [ XQ UNREF’D OPTIONS] examines t hose optio ns that ar e not:
	7678	Located on any menu.
	7679	Used as pr imary or s econdary o ptions.
	7680	Tasked to run.
	7681	The user c an then de cide in ea ch case wh ether to d elete the unreferenc ed option.
	7682	Global Blo ck Count O ption
	7683	The Global Block Cou nt option [XU BLOCK COUNT] can be used t o count th e number o f data blo cks in a g lobal.
	7684	Listing Gl obals Opti on
	7685	The List G lobal opti on [XUPRGL ] is found on the Pr ogrammer O ptions men u, locked with the X UPROG key. This opti on is also locked wi th the XUP ROGMODE ke y as an ex tra level of securit y.
	7686	It can be used to li st the con tents of a global to the scree n. It make s use of o perating s ystem-spec ific utili ties such as %G, the Global Li ster.
	7687	The option is locked with the XUPROGMODE security key
	7688	The corres ponding di rect mode utility ca n be used in program mer mode. For exampl e:
	7689	>D ^%G (OS -specific)
	7690	Test an op tion not i n your men u Option
	7691	Use the Te st an opti on not in your menu option [XT -OPTION TE ST] for in -house tes ting of op tions only . It allow s the sele ction of a n option f rom the OP TION file (#19) and then execu tes it. Th is option is locked with the X UMGR secur ity key.
	7692	CAUTION: N o security checks ar e performe d in the X T-OPTION T EST option ; therefor e, it shou ld only be given to programmer s.
	7693	REF: Kerne l Toolkit Applicatio n Programm ing Interf aces (APIs ) are docu mented in the “Toolk it: Develo per Tools” section i n the Kern el Develop er’s Guide . Kernel a nd Kernel Toolkit AP Is are als o availabl e in HTML format on the VA Int ranet Webs ite.
	7694	^%Z Editor
	7695	User Inter face
	7696	The ^%Z ed itor (rout ine editor ) is insta lled in th e Manager account as the ^%Z g lobal by Z TMGRSET du ring insta llation. ( It can als o be insta lled with D ^ZTEDIT. ) To use t he editor, load the routine (i t must pre -exist) an d then X ^ %Z. The fo llowing ex ample crea tes a one- line routi ne in Cach é and then calls the ^%Z Edito r.
	7697	Figure 80: Calling t he ^%Z Edi tor—Sample user entr ies
	7698	>ZR
	7699
	7700	>ZZTEST <E nter> ;ID/ SITE;test routine;
	7701	>ZS ZZTEST
	7702
	7703	The editor fills in the third “<space>;” piece wit h the date /time that the routi ne is file d.
	7704	The editor fills in the third “<space>;” piece wit h the date /time that the routi ne is file d.
	7705
	7706	>ZL ZZTEST X ^%Z
	7707
	7708	%Z Editing : ZZTEST Terminal t ype: C-VT1 00
	7709	Edit:
	7710
	7711	Enter “.F” (dot-file ) at the e dit prompt to change files. Wh en saving with dot-f ile, an ed it comment can be en tered. Thi s text is stored in the EDIT H ISTORY mul tiple in t he ROUTINE file (#9. 8) as prog rammer doc umentation . The foll owing exam ple shows how an ent ire routin e can be d isplayed b y entering the ZP pr int comman d followed by a spac e at the M prompt. D ot-file (. File) is t hen used t o file. A dot is the n used to exit. (The dot exit does not a utomatical ly file ch anges.)
	7712	Figure 81: ^%Z Edito r—Displayi ng a routi ne using t he ZP comm and
	7713	>ZL ZZTEST X ^%Z
	7714
	7715	%Z Editing : ZZTEST Terminal t ype: C-VT1 00
	7716	Edit: ZP<S PACE> <Ent er>
	7717	ZZTEST ; test routi ne
	7718
	7719	Length: 2 0 <Enter> Line: ZZT EST
	7720	ZZTEST ;te st routine
	7721	Edit: .Ins ert after: ZZTEST// <Enter>
	7722
	7723	First, eit her a <Tab > or line label is e ntered.
	7724	First, eit her a <Tab > or line label is e ntered.
	7725	Line: ; NEXT LINE
	7726	Line: Q
	7727	Line: <Ent er>
	7728	Edit: .FIL E ZZTEST
	7729	Edit comme nt:
	7730	1> This text is st ored in th e Routine file’s Edi t History multiple. <Enter>
	7731	2> <Ente r>
	7732	EDIT Optio n: <Enter>
	7733	Edit: . <E nter>
	7734	>
	7735
	7736	Routines a re filed b y the name used when loading, not by the first lin e tag. If a ROUTINE file (#9.8 ) exists, then the r outine is added if n ot already there, an d an entry is made o f the date /time and DUZ of the user that filed it. When fili ng, the ed itor updat es the thi rd piece o f the firs t line of the routin e with the date/time .
	7737	When editi ng, a ques tion mark (“?”) can be entered to provid e help. Th e dot comm ands are l isted firs t. They pr ovide the usual brea k, join, i nsert, and remove fu nctions. T he +n meth od of sele cting line s to edit is also no ted. The l ine tag ca n be used along with a number (e.g., TAG +3) to rea ch a parti cular line . A minus sign (“-”) backs up lines. And the aster isk (“*”) can be ent ered to re ach the la st line.
	7738	Figure 82: ^%Z Edito r—Listing edit comma nds
	7739	>X ^%Z
	7740	Edit: ?
	7741	.ACTION me nu .BRE AK line .CHANGE e very
	7742	.FILE rout ine .INS ERT after .JOIN lin es
	7743	.MOVE line s .REM OVE lines .SEARCH f or
	7744	.TERMinal type .XY change to/ from repla ce-with
	7745	. -TO EXIT THE EDITO R
	7746	“”+n Absol ute line n +n To advance n lines -n To backup n lines_
	7747	use ‘*’ t o get last line
	7748
	7749	^NAME - to edit a GL OBAL node *NA ME - to ed it a LOCAL variable
	7750	MUMPS comm and line ( mumps comm and <space > or Z com mand <spac e>)
	7751
	7752	Help displ ays inform ation abou t editing in line mo de. A comp lete line is display ed and var ious keys can be use d to navig ate. The < Spacebar> moves forw ard by wor ds, the pe riod moves forward b y characte rs, and th e <CTRL H> command k ey sequenc e moves ba ckwards by character s. Upon re aching the desired l ocation, t he <Delete > key can be used to remove ch aracters. To enter c haracters, the chara cter “E” m ust first be entered as an ins ert/delete toggle. P ressing th e <Enter> key revers es the tog gle and al lows navig ation. Pre ssing the <Enter> ke y again mo ves back t o the begi nning of t he line.
	7753	Figure 83: ^%Z Edito r—Line mod e help inf ormation
	7754	In the lin e mode,
	7755	Spacebar m oves to th e next spa ce or comm a. Dot to the next c har.
	7756	‘>‘ To mov e forward 80 char or to end of line.
	7757	Backspace to back up one char. E to ente r new char ’s at the cursor.
	7758	CR to exit enter mod e, return to start o f line or EDIT promp t.
	7759	D to delet e from the cursor to the next space or c omma.
	7760	Delete (Ru b) to dele te the cha r under th e cursor.
	7761	CTRL-R to restore li ne and sta rt back at the begin ning.
	7762
	7763	Replace mo de editing can be in voked by e ntering do t-XY at th e edit pro mpt. This method all ows easy s tring subs titution, as in VA F ileMan’s L ine Editor . Entering a questio n mark at the next e dit prompt displays the follow ing help:
	7764	Figure 84: ^%Z Edito r—Replace mode editi ng help in formation
	7765	In the rep lace/with mode,
	7766	SPECIAL <R EPLACE> ST RINGS:
	7767	END - to add to the END of a line
	7768	... - to replace a line
	7769	A...B - to specify a string that begin s with “A” and ends with “B”
	7770	A... - to specify a string that begin s with “A” to the en d of the l ine
	7771	CTRL-R to restore li ne.
	7772
	7773	The ACTION menu prov ides addit ional func tions. Sav e and rest ore lines can be use d to move lines with in one rou tine or fr om one rou tine to an other. To copy lines to anothe r routine, first sav e the line s, then lo ad and edi t the othe r routine, and resto re the lin es. When patch ing a rout ine, the A CTION menu can be us ed to calc ulate chec ksums. Bef ore filing changes, the new ch ecksum can be displa yed and co mpared wit h the patc h report f or verific ation of e diting. Fi gure 85 sh ows how to reach the ACTION me nu with do t-A (.A).

	7774	Figure 85: ACTION me nu—Sample user entri es
	7775	Edit: .A
	7776	Action: ?
	7777	Bytes in r outine Che cksum Restore lines
	7778	Save lines Ver sion #
	7779	Action: C
	7780	Checksum i s 4971725
	7781	Action: <E nter>
	7782	Edit: <Ent er>
	7783
	7784	Global nod es and loc al variabl es may als o be edite d with the ^%Z edito r. Editing occurs di rectly, so the idea of filing does not a pply. The editor mus t then be exited wit h a dot, n ot with a dot-file, since fili ng should not take p lace.
	7785	Applicatio n Programm ing Interf ace (API)
	7786	The follow ing are mi scellaneou s APIs ava ilable for developer s. These A PIs are de scribed be low.
	7787	Progress B ar Emulato r
	7788	The follow ing APIs c an be use d to emula te a KIDS Progress B ar outside of KIDS. To create the progre ss bar, yo u must fir st call th e INIT^XPD ID: Progre ss Bar Emu lator: Ini tialize De vice and D raw Box Bo rders API, and when you are fi nished, yo u must cal l the EXIT ^XPDID(): Progress B ar Emulato r: Restore Screen, C lean Up Va riables, a nd Display Text API.
	7789	INIT^XPDID : Progress Bar Emula tor: Initi alize Devi ce and Dra w Box Bord ers
	7790	Reference Type:Suppo rted
	7791	Category:M iscellaneo us
	7792	ICR #:2172
	7793	Descriptio n:This API initializ es the dev ice, draws the borde rs for the progress bar box, a nd draws t he progres s bar. Whe n you are finished, you must c all the EX IT^XPDID() : Progress Bar Emula tor: Resto re Screen, Clean Up Variables, and Displ ay Text AP I.
	7794	Format:INI T^XPDID
	7795	Input Para meters:non e.
	7796	Output:ret urns:Retur ns XPDIDVT :
	7797	1—If outpu t device s upports gr aphics.
	7798	0—If outpu t device d oes not su pport grap hics.
	7799
	7800	TITLE^XPDI D(): Progr ess Bar Em ulator: Di splay Titl e Text
	7801	Reference Type:Suppo rted
	7802	Category:M iscellaneo us
	7803	ICR #:2172
	7804	Descriptio n:This API displays the text i n the x in put parame ter as a t itle at th e top of t he progres s bar box.
	7805	Format:TIT LE^XPDID(x )
	7806	Input Para meters:x:( required) Title text to be dis played at the top of the box.
	7807	Output:non e.
	7808
	7809	EXIT^XPDID (): Progre ss Bar Emu lator: Res tore Scree n, Clean U p Variable s, and Dis play Text
	7810	Reference Type:Suppo rted
	7811	Category:M iscellaneo us
	7812	ICR #:2172
	7813	Descriptio n:This API restores the screen to normal , cleans u p all vari ables, and displays the text i n the x in put parame ter.
	7814	Format:EXI T^XPDID(x)
	7815	Input Para meters:x:( required) Text to di splay on s creen afte r removing box and p rogress ba r.
	7816	Output:non e.
	7817
	7818	Lookup Uti lity
	7819	$$EN^XUA4A 71(): Conv ert String to Sounde x
	7820	Reference Type:Suppo rted
	7821	Category:M iscellaneo us
	7822	ICR #:3178
	7823	Descriptio n:This ext rinsic fun ction conv erts a str ing into a numeric r epresentat ion of the string, u sing sound ex methods . Soundex represents the phone tic proper ties of a string; it s chief fe ature is t hat it ass igns simil ar strings the same soundex re presentati on.
	7824	Format:$$E N^XUA4A71( string)
	7825	Input Para meters:str ing:(requi red) Strin g to conve rt into so undex form .
	7826	Output:ret urns:Retur ns the sou ndex versi on of the string.
	7827
	7828	Date Conve rsions and Calculati ons
	7829	^XQDATE: C onvert $H to VA File Man Format (Obsolete )
	7830	NOTE: This API is ob solete. Yo u should u se either of the fol lowing API s instead:
	7831	$$FMTE^XLF DT(): Conv ert VA Fil eMan Date to Externa l Format
	7832	$$HTFM^XLF DT(): Conv ert $H to VA FileMan Date Form at
	7833
	7834	Reference Type:Suppo rted
	7835	Category:M iscellaneo us
	7836	ICR #:1007 9
	7837	Descriptio n:This API converts $H formatt ed input d ate to a V A FileMan formatted date in %, and in hu man readab le format (e.g., Jan . 9, 1990 1:37 PM) i n %Y varia ble.
	7838	Format:^XQ DATE
	7839	Make sure to perform the follo wing steps before ca lling this API:
	7840	NEW all no n-namespac ed variabl es.
	7841	Set all in put variab les.
	7842	Call the A PI.
	7843	Input Vari able s:XQD 1:(optiona l) If this variable is not set , the syst em uses $H .
	7844	Output Var iables:%:R eturns the converted $H date i n VA FileM an format.
	7845	%Y:Returns the conve rted $H da te, in hum an readabl e format.
	7846
	7847	^XUWORKDY: Workday C alculation (Obsolete )
	7848	NOTE: This API is ob solete. Th e XUWORKDY routine i s maintain ed for cod e that mig ht still u se it.
	7849	Reference Type:Suppo rted
	7850	Category:M iscellaneo us
	7851	ICR #:1004 6
	7852	Descriptio n:To use t he ^XUWORK DY APIs, y ou must ma ke sure th at HOLIDAY file (#40 .5) is pop ulated wit h each yea r’s holida ys for the workday c alculation to work c orrectly. If it is n ot populat ed, you ne ed to popu late it yo urself (Ke rnel distr ibutes thi s file wit hout data) . Only ent er holiday s that fal l on weekd ays, howev er.
	7853	You can ca ll the ^XU WORKDY rou tine to ca lculate th e number o f workdays between t wo dates ( X, X1). It returns a positive value if X <X1 and a negative v alue if X> X1. If eit her date i s imprecis ely specif ied, or if the HOLID AY global is empty, then ^XUWO RKDY retur ns a NULL string.
	7854	The first FOR loop i n ^XUWORKD Y checks t he HOLIDAY global an d sets %H equal to t he number of holiday s between the two da tes. It is assumed t hat the HO LIDAY glob al contain s only wee kday holid ays.
	7855	The second FOR loop (F %J=%J:1 ... ) ste ps forward from the earliest d ate and st ops at the first Sun day or at the ending date (whi chever com es first) counting t he number of workday s.
	7856	The third FOR loop ( F %K=%K:-1 ... ) ste ps backwar d from the latest da te and sto ps at the first Sund ay or at t he beginni ng date (w hichever c omes first ), countin g the work days.
	7857	Then %I is set equal to the nu mber of da ys between the two S undays.
	7858	Finally, X is set eq ual to the total cou nted days minus the number of weekend da ys between the two S undays ( - (%I\7*2) ) .
	7859	Format:^XU WORKDY
	7860	Make sure to perform the follo wing steps before ca lling this API:
	7861	NEW all no n-namespac ed variabl es.
	7862	Set all in put variab les.
	7863	Call the A PI.
	7864	Input Vari ables:X:(r equired) S tarting da te in VA F ileMan int ernal form at (e.g., 2850420).
	7865	X1:(requir ed) Ending date in V A FileMan internal f ormat (e.g ., 2850707 ).
	7866	Output:X:T he number of workday s in the i nterval.
	7867
	7868	Example
	7869	>S X=28504 20,X1=2850 707 D ^XUW ORKDY W X
	7870
	7871	55
	7872
	7873	$$EN^XUWOR KDY: Numbe r of Workd ays Calcul ation
	7874	NOTE: The XUWORKDY r outine is maintained for code that might still use it.
	7875	Reference Type:Suppo rted
	7876	Category:M iscellaneo us
	7877	ICR #:1004 6
	7878	Descriptio n:To use t he ^XUWORK DY APIs, y ou must ma ke sure th at HOLIDAY file (#40 .5) is pop ulated wit h each yea r’s holida ys for the workday c alculation to work c orrectly. If it is n ot populat ed, you ne ed to popu late it yo urself (Ke rnel distr ibutes thi s file wit hout data) . Only ent er holiday s that fal l on weekd ays, howev er.
	7879	The $$EN^X UWORKDY ex trinsic fu nction cal culates th e number o f workdays between t wo dates ( date1, dat e2). It re turns a po sitive val ue if date 1<date2 an d a negati ve value i f date1>da te2. If ei ther date is impreci sely speci fied, or i f the HOLI DAY global is empty, then $$EN ^XUWORKDY returns a NULL strin g.
	7880	The first FOR loop i n ^XUWORKD Y checks t he HOLIDAY global an d sets %H equal to t he number of holiday s between the two da tes. It is assumed t hat the HO LIDAY glob al contain s only wee kday holid ays.
	7881	The second FOR loop (F %J=%J:1 ... ) ste ps forward from the earliest d ate and st ops at the first Sun day or at the ending date (whi chever com es first) counting t he number of workday s.
	7882	The third FOR loop ( F %K=%K:-1 ... ) ste ps backwar d from the latest da te and sto ps at the first Sund ay or at t he beginni ng date (w hichever c omes first ), countin g the work days.
	7883	Then %I is set equal to the nu mber of da ys between the two S undays.
	7884	Finally, t he return value is s et equal t o the tota l counted days minus the numbe r of weeke nd days be tween the two Sunday s ( -(%I\7 *2) ).
	7885	Format:$$E N^XUWORKDY (date1,dat e2)
	7886	Input Para meters:dat e1:(requir ed) Starti ng date in VA FileMa n internal format (e .g., 28504 20).
	7887	date2:(req uired) End ing date i n VA FileM an interna l format ( e.g., 2850 707).
	7888	Output:ret urns:Retur ns the num ber of wor kdays in t he interva l.
	7889
	7890	Example
	7891	>W $$EN^XU WORKDY(309 0102,30901 08)
	7892	4
	7893
	7894	$$WORKDAY^ XUWORKDY: Workday Va lidation
	7895	NOTE: The XUWORKDY r outine is maintained for code that might still use it.
	7896	Reference Type:Suppo rted
	7897	Category:M iscellaneo us
	7898	ICR #:1004 6
	7899	Descriptio n:To use t he ^XUWORK DY APIs, y ou must ma ke sure th at HOLIDAY file (#40 .5) is pop ulated wit h each yea r’s holida ys for the workday c alculation to work c orrectly. If it is n ot populat ed, you ne ed to popu late it yo urself (Ke rnel distr ibutes thi s file wit hout data) . Only ent er holiday s that fal l on weekd ays, howev er.
	7900	The $$WORK DAY^XUWORK DY extrins ic functio n returns 1 if the d ate submit ted is a w orkday and 0 if it i s not. If the date i s imprecis ely specif ied, or if the HOLID AY global is empty, then $$WOR KDAY^XUWOR KDY return s a NULL s tring.
	7901	Format:$$W ORKDAY^XUW ORKDY(date )
	7902	Input Para meters:dat e:(require d) Startin g date in VA FileMan internal format ret urns: (e.g ., 2850420 ).
	7903	Output:Ret urns:
	7904	1—Workday
	7905	0—Non-Work day
	7906
	7907	Examples
	7908	Example 1
	7909	This examp le shows t he return value when a workday in VA Fil eMan inter nal format is input:
	7910	>W $$WORKD AY^XUWORKD Y(3090102)
	7911	1
	7912
	7913	Example 2
	7914	This examp le shows t he return value when a non-wor kday in VA FileMan i nternal fo rmat is in put:
	7915	>W $$WORKD AY^XUWORKD Y(3090103)
	7916	0
	7917
	7918	$$WORKPLUS ^XUWORKDY: Workday O ffset Calc ulation
	7919	NOTE: The XUWORKDY r outine is maintained for code that might still use it.
	7920	Reference Type:Suppo rted
	7921	Category:M iscellaneo us
	7922	ICR #:1004 6
	7923	Descriptio n:To use t he ^XUWORK DY APIs, y ou must ma ke sure th at HOLIDAY file (#40 .5) is pop ulated wit h each yea r’s holida ys for the workday c alculation to work c orrectly. If it is n ot populat ed, you ne ed to popu late it yo urself (Ke rnel distr ibutes thi s file wit hout data) . Only ent er holiday s that fal l on weekd ays, howev er.
	7924	The $$WORK PLUS^XUWOR KDY extrin sic functi on returns the date that is “n ” working days (i.e. , offset) +/- of the input dat e. If the date is im precisely specified, or if the HOLIDAY g lobal is e mpty, then $$WORKPLU S^XUWORKDY returns a NULL stri ng.
	7925	Format:$$W ORKPLUS^XU WORKDY(dat e,offset)
	7926	Input Para meters:dat e:(require d) Startin g date in VA FileMan internal format (e. g., 285042 0).
	7927	offset: (r equired) T he number of days to offset.
	7928	Output:ret urns:Retur ns the dat e in VA Fi leMan inte rnal forma t that is “n” workin g days (i. e., offset ) +/- of t he input d ate.
	7929
	7930	Example
	7931	>W $$WORKP LUS^XUWORK DY(3090108 ,3)
	7932	3090113
	7933
	7934
	7935	Name Stand ardization : Develope r Tools
	7936	Applicatio n Programm ing Interf ace (API)
	7937	Several AP Is are ava ilable for developer s to work with name standardiz ation. The se APIs ar e describe d below.
	7938	$$BLDNAME^ XLFNAME(): Build Nam e from Com ponent Par ts
	7939	Reference Type:Suppo rted
	7940	Category:N ame Standa rdization
	7941	ICR #:3065
	7942	Descriptio n:This ext rinsic fun ction take s the comp onent part s of a nam e and retu rns the na me, trunca ted if nec essary, in the follo wing forma t:
	7943	Family_nam e,Given_na me<space>M iddle_name <space>Suf fix(es)
	7944	Format:$$B LDNAME^XLF NAME(.name [,max])
	7945	Input Para meters:.na me:(requir ed) The co mponent pa rts of the name:
	7946	NAME(“FAMI LY”) = Fam ily (Last) Name
	7947	NAME(“GIVE N”) = Give n (First) Name(s)
	7948	NAME(“MIDD LE”) = Mid dle Name(s )
	7949	NAME(“SUFF IX”) = Suf fix(es)
	7950	Alternativ ely, this array can contain th e file num ber, IENS, and field number of the field that cont ains the n ame. If th e name has a corresp onding ent ry in the NAME COMPO NENTS file (#20), th en the nam e componen ts are obt ained from that entr y. Otherwi se, the na me is obta ined direc tly from t he file, r ecord, and field spe cified, an d the name component s are obta ined by ma king a cal l to the S TDNAME^XLF NAME(): Na me Standar dization R outine API .
	7951	NAME(“FILE ”) = Sourc e file num ber (requi red)
	7952	NAME(“IENS ”) = IENS of entry i n the sour ce file (r equired)
	7953	NAME(“FIEL D”) = Sour ce field n umber (req uired)
	7954	max:(optio nal) The m aximum len gth of the Name to b e returned (default = 256).
	7955	REF: For a descripti on of the pruning al gorithm, s ee the “De tails” sec tion.
	7956	Output:ret urns:Retur ns the nam e, truncat ed if nece ssary, in the follow ing format :
	7957	Family_nam e,Given_na me<space>M iddle_name <space>Suf fix(es)
	7958
	7959	Details
	7960	If the max input par ameter is used, and the result ing name i s longer t han max, t he followi ng pruning algorithm is perfor med to sho rten the n ame:
	7961	Truncate M iddle Name from the right-most position until only the initi al charact er is left .
	7962	Drop suffi x.
	7963	Truncate G iven Name from the r ight-most position u ntil only the initia l characte r is left.
	7964	Truncate F amily Name from the right-most position.
	7965	Truncate t he name fr om the rig ht.
	7966	Examples
	7967	Example 1
	7968	Suppose th e MYNAME a rray conta ins the fo llowing el ements:
	7969	MYNAME(“FA MILY”)=“XU USER”
	7970	MYNAME(“GI VEN”)=“SIX TY”
	7971	MYNAME(“MI DDLE”)=“K. ”
	7972	MYNAME(“SU FFIX”)=“JR ”
	7973
	7974	Calls to $ $BLDNAME^X LFNAME ret urns the n ame as fol lows:
	7975	>S X=$$BLD NAME^XLFNA ME(.MYNAME )
	7976
	7977	>W X
	7978	XUUSER,SIX TY K JR
	7979
	7980	“Pruning” the name t o 12 chara cters tota l:
	7981	>S X=$$BLD NAME^XLFNA ME(.MYNAME ,12)
	7982
	7983	>W X
	7984	XUUSER,SI K
	7985
	7986	Example 2
	7987	If an entr y in the N AME COMPON ENTS file (#20) stor es the com ponents of a name st ored in th e NAME fie ld (#.01) of record number 32 in the NEW PERSON fi le (#200), and the d ata in the correspon ding recor d in the N AME COMPON ENT file ( #20) is:
	7988	FILE=200
	7989	FIELD=.01
	7990	IENS=“32,”
	7991	GIVEN NAME =“SIXTY”
	7992	MIDDLE NAM E=“K.”
	7993	FAMILY NAM E=“XUUSER”
	7994	SUFFIX=“JR ”
	7995
	7996	You can se t:
	7997	MYNAME(“FI LE”)=200
	7998	MYNAME(“FI ELD”)=.01
	7999	MYNAME(“IE NS”)=“32,”
	8000
	8001	Then call $$BLDNAME^ XLFNAME as in Exampl e 1:
	8002	>S X=$$BLD NAME^XLFNA ME(.MYNAME )
	8003
	8004	>W X
	8005	XUUSER,SIX TY K JR
	8006
	8007	“Pruning” the name t o 12 chara cters tota l:
	8008	>S X=$$BLD NAME^XLFNA ME(.MYNAME ,12)
	8009
	8010	>W X
	8011	XUUSER,SI K
	8012
	8013	$$CLEANC^X LFNAME(): Name Compo nent Stand ardization Routine
	8014	Reference Type:Suppo rted
	8015	Category:N ame Standa rdization
	8016	ICR #:3065
	8017	Descriptio n:This ext rinsic fun ction take s a single name comp onent and returns th at name in standard format.
	8018	Format:$$C LEANC^XLFN AME(comp[, flags])
	8019	Input Para meters:com p:(require d) The nam e componen t to be co nverted to standard format.
	8020	flags:(opt ional) Fla g to contr ol process ing. Possi ble values are:
	8021	F—If the n ame compon ent to be converted is the FAM ILY (LAST) NAME, pas s the “F” flag. With the “F” f lag, colon s (:), sem icolons (; ), and com mas (,) ar e converte d to hyphe ns (-). Sp aces and a ll punctua tion excep t hyphens are remove d. Two or more conse cutive spa ces or hyp hens are r eplaced wi th a singl e space or hyphen. B irth posit ion indica tors 1ST t hrough 10T H are chan ged to the ir Roman n umeral equ ivalents.
	8022	NULL—Witho ut the “F” flag, the component is conver ted to upp er case. C olons (:), semicolon s (;), com mas (,), a nd periods (.) are c onverted t o spaces. All punctu ation exce pt for hyp hens and s paces are removed. T wo or more consecuti ve spaces or hyphens are repla ced with a single sp ace or hyp hen. Birth position indicators 1ST throu gh 10TH ar e changed to their R oman numer al equival ents.
	8023	Output:ret urns:Retur ns the sta ndard form atted name .
	8024
	8025	Examples
	8026	Example 1
	8027	Standardiz e family ( last) name :
	8028	>Set X=$$C LEANC^XLFN AME(“XUUSE R-XU U SER ”,“F”)
	8029
	8030	>W X
	8031	XUUSER-XUU SER
	8032
	8033	>Set X=$$C LEANC^XLFN AME(“XUUSE R-XU U SER 2ND”,“F”)
	8034
	8035	>W X
	8036	XUUSER-XUU SERII
	8037
	8038	>Set X=$$C LEANC^XLFN AME(“XUUSE R-XU U SER ”)
	8039
	8040	>W X
	8041	XUUSER-XU U SER
	8042
	8043	>Set X=$$C LEANC^XLFN AME(“ST. U SER”,“F”)
	8044
	8045	>W X
	8046	STUSER
	8047
	8048	Example 2
	8049	Standardiz e other (n on-family) name comp onents:
	8050	>S X=$$CLE ANC^XLFNAM E(“F.O.”)
	8051
	8052	>W X
	8053	F O
	8054
	8055	>S X=$$CLE ANC^XLFNAM E(“FORTY’” )
	8056
	8057	>W X
	8058	FORTY
	8059
	8060	>S X=$$CLE ANC^XLFNAM E(“FORTY O NE”)
	8061
	8062	>W X
	8063	FORTY ONE
	8064
	8065	>S X=$$CLE ANC^XLFNAM E(“FORTY-O NE”)
	8066
	8067	>W X
	8068	FORTY-ONE
	8069
	8070	$$FMNAME^X LFNAME(): Convert HL 7 Formatte d Name to Name
	8071	Reference Type:Suppo rted
	8072	Category:N ame Standa rdization
	8073	ICR #:3065
	8074	Descriptio n:This ext rinsic fun ction conv erts an HL 7 formatte d input na me to a Vi stA format ted name.
	8075	Format:$$F MNAME^XLFN AME([.]nam e[,flags][ ,delim])
	8076	Input Para meters:[.] name:(requ ired) This is the HL 7 name to be convert ed; it can be passed by refere nce. If th e “C” flag is used, the name c omponents are return ed in node s descende nt from th is paramet er (see th e “Output” section b elow).
	8077	flags:(opt ional) Fla gs to cont rols proce ssing. Pos sible valu es are:
	8078	C—Return n ame compon ents in th e NAME arr ay (see th e “Output Parameters ” section below).
	8079	L#—Truncat e the retu rned name to a maxim um Length of # chara cters, whe re # is an integer b etween 1 a nd 256.
	8080	M—Return t he name in Mixed cas e, with th e first le tter of ea ch name co mponent ca pitalized.
	8081	S—Return t he name in Standardi zed form.
	8082	delim:(opt ional) The delimiter used in t he HL7 for matted nam e (default = “^”).
	8083	Output Par ameters:na me:If the FLAGS inpu t paramete r contains a “C”, th e componen t parts of the name are return ed in the NAME array :
	8084	NAME(“FAMI LY) = Fami ly (Last) NameNAME(“ GIVEN”) = Given (Fir st) Name(s )NAME(“MID DLE”) = Mi ddle Name( s)NAME(“SU FFIX”) = S uffix(es)
	8085
	8086	Details
	8087	If the L# flag is us ed, and th e resultin g name is longer tha n #, the f ollowing p runing alg orithm is performed to shorten the name:
	8088	Truncate M iddle Name from the right-most position until only the initi al charact er is left .
	8089	Drop suffi x.
	8090	Truncate G iven Name from the r ight-most position u ntil only the initia l characte r is left.
	8091	Truncate F amily Name from the right-most position.
	8092	Truncate t he name fr om the rig ht.
	8093	Examples
	8094	Example 1
	8095	Convert an HL7 forma tted name to a VistA name:
	8096	>S X=$$FMN AME^XLFNAM E(“XUUSER^ SIXTY^K.^J R^MR.^PHD” )
	8097
	8098	>W X
	8099	XUUSER,SIX TY K. JR
	8100
	8101	>S X=$$FMN AME^XLFNAM E(“XUUSER^ SIXTY^K.^J R^MR.^PHD” ,“S”)
	8102
	8103	>W X
	8104	XUUSER,SIX TY K JR
	8105
	8106	>S X=$$FMN AME^XLFNAM E(“XUUSER^ SIXTY^K.^J R^MR.^PHD” ,“M”)
	8107
	8108	>W X
	8109	Xuuser,Six ty K. Jr
	8110
	8111	>S X=$$FMN AME^XLFNAM E(“XUUSER^ SIXTY^K.^J R^MR.^PHD” ,“SL12”)
	8112
	8113	>W X
	8114	XUUSER,SI K
	8115
	8116	Example 2
	8117	Convert an HL7 forma tted name where “~” is the del imiter to a standard name:
	8118	>S X=$$FMN AME^XLFNAM E(“XUUSER~ SIXTY~K.~J R~MR”,“S”, “~”)
	8119
	8120	>W X
	8121	XUUSER,SIX TY K JR
	8122
	8123	Example 3
	8124	Convert an HL7 forma tted name to a stand ard name, and return the compo nents of t hat name i n the MYNA ME array:
	8125	Figure 86: $$FMNAME^ XLFNAME AP I—Example: Convertin g an HL7 f ormatted n ame to a s tandard na me, and re turning th e componen ts in an a rray
	8126	>S MYNAME= “XUUSER^SI XTY^K.^JR^ MR.^PHD”
	8127
	8128	>W $$FMNAM E^XLFNAME( .MYNAME,“C S”)
	8129	XUUSER,SIX TY K JR
	8130
	8131	>ZW MYNAME
	8132	MYNAME=XUU SER^SIXTY^ K.^JR^MR.^ PHD
	8133	MYNAME(“DE GREE”)=PHD
	8134	MYNAME(“FA MILY”)=XUU SER
	8135	MYNAME(“GI VEN”)=SIXT Y
	8136	MYNAME(“MI DDLE”)=K.
	8137	MYNAME(“PR EFIX”)=MR.
	8138	MYNAME(“SU FFIX”)=JR
	8139
	8140	$$HLNAME^X LFNAME(): Convert Na me to HL7 Formatted Name
	8141	Reference Type:Suppo rted
	8142	Category:N ame Standa rdization
	8143	ICR #:3065
	8144	Descriptio n:This ext rinsic fun ction conv erts an in put name t o an HL7 f ormatted n ame.
	8145	Format:$$H LNAME^XLFN AME([.]nam e[,flags][ ,delim])
	8146	Input Para meters:[.] name:(requ ired) The component parts of t he name to be conver ted:
	8147	NAME(“FAMI LY) = Fami ly (Last) Name (requ ired)NAME( “GIVEN”) = Given (Fi rst) Name( s) (option al)NAME(“M IDDLE”) = Middle Nam e(s) (opti onal)NAME( “SUFFIX”) = Suffix(e s) (option al)NAME(“P REFIX”) = Prefix (op tional)NAM E(“DEGREE” ) = Degree (optional )
	8148	Alternativ ely, this array can contain th e file num ber, IENS, and field number of the field that cont ains the n ame. If th e name has a corresp onding ent ry in the NAME COMPO NENTS file (#20), th en the nam e componen ts are obt ained from that entr y. Otherwi se, the na me is obta ined direc tly from t he file, r ecord, and field spe cified, an d the name component s are obta ined by ma king a cal l to the S TDNAME^XLF NAME(): Na me Standar dization R outine API .
	8149	NAME(“FILE ”) = Sourc e file num ber (requi red)NAME(“ IENS”) = I ENS of ent ry in the source fil e (require d)NAME(“FI ELD”) = So urce field number (r equired)
	8150	Another al ternative is to pass in the un subscripte d NAME par ameter the name to b e converte d. $$HLNAM E^XLFNAME obtains th e componen ts parts o f that nam e by makin g a call t o the STDN AME^XLFNAM E(): Name Standardiz ation Rout ine API. T his altern ative is r ecommended only for names that do not ha ve associa ted entrie s on the N AME COMPON ENTS file (#20).
	8151	flags:(opt ional) Fla gs to cont rols proce ssing. Pos sible valu es are:
	8152	L#—Truncat e the retu rned name to a maxim um Length of # chara cters, whe re # is an integer b etween 1 a nd 256.
	8153	S—Return t he name co mponents i n the HL7 formatted name in St andardized form.
	8154	delim:(opt ional) The delimiter to use in the HL7 s tring (def ault = “^” ).
	8155	Output:ret urns:Retur ns the con verted nam e in HL7 f ormat.
	8156
	8157	Details
	8158	If the L# flag is us ed, and th e resultin g name is longer tha n #, the f ollowing p runing alg orithm is performed to shorten the name:
	8159	Truncate M iddle Name from the right-most position until only the initi al charact er is left .
	8160	Drop suffi x.
	8161	Truncate G iven Name from the r ight-most position u ntil only the initia l characte r is left.
	8162	Truncate F amily Name from the right-most position.
	8163	Truncate t he name fr om the rig ht.
	8164	Examples
	8165	Example 1
	8166	Suppose th e MYNAME a rray conta ins the fo llowing el ements:
	8167	MYNAME(“PR EFIX”)=“MR .”MYNAME(“ GIVEN”)=“S IXTY”MYNAM E(“MIDDLE” )=“K.”MYNA ME(“FAMILY ”)=“XUUSER ”MYNAME(“S UFFIX”)=“J R”MYNAME(“ DEGREE”)=“ PHD”
	8168
	8169	Then calls to the $$ HLNAME^XLF NAME API r eturns the name as f ollows:
	8170	>S X=$$HLN AME^XLFNAM E(.MYNAME)
	8171
	8172	>W X
	8173	XUUSER^SIX TY^K.^JR^M R.^PHD
	8174
	8175	>S X=$$HLN AME^XLFNAM E(.MYNAME, “”,“~”)
	8176
	8177	>W X
	8178	XUUSER~SIX TY~K.~JR~M R.~PHD
	8179
	8180	>S X=$$HLN AME^XLFNAM E(.MYNAME, “S”,“~”)
	8181
	8182	>W X
	8183	XUUSER~SIX TY~K~JR~MR ~PHD
	8184
	8185	>S X=$$HLN AME^XLFNAM E(.MYNAME, “L12S”)
	8186
	8187	>W X
	8188	XUUSER^SI^ K
	8189
	8190	Example 2
	8191	If an entr y in the N AME COMPON ENTS file (#20) stor es the com ponents of a name st ored in th e NAME fie ld (#.01) of record number 32 in the NEW PERSON fi le (#200), and the d ata in the correspon ding recor d in the N AME COMPON ENTS file (#20) is:
	8192	FILE = 200 FIELD = .0 1IENS = “3 2,”PREFIX = “MR.”GIV EN NAME = “SIXTY”MID DLE NAME = “K.”FAMIL Y NAME = “ XUUSER”SUF FIX = “JR” DEGREE = “ PHD”
	8193
	8194	You can se t:
	8195	MYNAME(“FI LE”) = 200 MYNAME(“FI ELD”) = .0 1MYNAME(“I ENS”) = “3 2,”
	8196
	8197	Then call the $$HLNA ME^XLFNAME API, as i n Example 1, to retu rn the nam e in vario us formats .
	8198	Example 3
	8199	Convert a name passe d by value to HL7 fo rmat:
	8200	>S X=$$HLN AME^XLFNAM E(“XUUSER, SIXTY HOWA RD II”)
	8201
	8202	>W X
	8203	XUUSER^SIX TY^HOWARD^ II
	8204
	8205	>S X=$$HLN AME^XLFNAM E(“XUUSER, SIXTY HOWA RD II”,“S” )
	8206
	8207	>W X
	8208	XUUSER^SIX TY^HOWARD^ II
	8209
	8210	>S X=$$HLN AME^XLFNAM E(“XUUSER, SIXTY HOWA RD II”,“SL 10”,“~”)
	8211
	8212	>W X
	8213	XUUSE~S~H
	8214
	8215	NAMECOMP^X LFNAME(): Component Parts from Standard Name
	8216	Reference Type:Suppo rted
	8217	Category:N ame Standa rdization
	8218	ICR #:3065
	8219	Descriptio n:This API takes a n ame in sta ndard form at and ret urns in an array the component parts of that name.
	8220	Format:NAM ECOMP^XLFN AME(.name)
	8221	Input Para meters:.na me:(requir ed) This p arameter i s the name in standa rd format to be pars ed. NAMECO MP^XLFNAME returns t he compone nt parts o f the name in nodes descendent from NAME . (See the “Output P arameters” section b elow.)
	8222	Output Par ameters:.n ame:The co mponent pa rts of the name are returned i n the NAME array pas sed in.
	8223	NAME(“FAMI LY) = Fami ly (last) NameNAME(“ GIVEN”) = Given (fir st) NameNA ME(“MIDDLE ”) = Middl e NameNAME (“SUFFIX”) = Suffix( es)
	8224	Example
	8225	In this ex ample, the MYNAME va riable is set to the standard name. The NAMECOMP^X LFNAME cal l is made to return in the MYN AME array the compon ent parts of that na me:
	8226	Figure 87: NAMECOMP^ XLFNAME AP I—Example
	8227	>S MYNAME= “XUUSER-XU USER,FORTY ONE S MD”
	8228	>D NAMECOM P^XLFNAME( .MYNAME)
	8229
	8230	>ZW MYNAME
	8231	MYNAME=XUU SER-XUUSER ,FORTY ONE S MD
	8232	MYNAME(“FA MILY”)=XUU SER-XUUSER
	8233	MYNAME(“GI VEN”)=FORT Y ONE
	8234	MYNAME(“MI DDLE”)=S
	8235	MYNAME(“SU FFIX”)=MD
	8236
	8237	$$NAMEFMT^ XLFNAME(): Formatted Name from Name Comp onents
	8238	Reference Type:Suppo rted
	8239	Category:N ame Standa rdization
	8240	ICR #:3065
	8241	Descriptio n:This ext rinsic fun ction retu rns a name converted to a form useful fo r display.
	8242	Format:$$N AMEFMT^XLF NAME(.name [,format][ ,flags])
	8243	Input Para meters:.na me:(requir ed) An arr ay that co ntains the component parts of the name:
	8244	NAME(“FAMI LY) = Fami ly (Last) Name (requ ired)NAME( “GIVEN”) = Given (Fi rst) Name( s) (option al)NAME(“M IDDLE”) = Middle Nam e(s) (opti onal)NAME( “SUFFIX”) = Suffix(e s) (option al)NAME(“P REFIX”) = Prefix (op tional)NAM E(“DEGREE” ) = Degree (optional )
	8245	Alternativ ely, this array can contain th e file num ber, IENS, and field number of the field that cont ains the n ame. If th e name has a corresp onding ent ry in the NAME COMPO NENTS file (#20), th en the nam e componen ts are obt ained from that entr y. Otherwi se, the na me is obta ined direc tly from t he file, r ecord, and field spe cified, an d the name component s are obta ined by ma king a cal l to the S TDNAME^XLF NAME(): Na me Standar dization R outine API .
	8246	NAME(“FILE ”) = Sourc e file num ber (requi red)NAME(“ IENS”) = I ENS of ent ry in the source fil e (require d)NAME(“FI ELD”) = So urce field number (r equired)
	8247	format:(op tional) Co ntrols the general f ormatting of the out put (defau lt = G). P ossible va lues are:
	8248	F—Return F amily (Las t) Name fi rst.
	8249	G—Return G iven (Firs t) Name fi rst.
	8250	O—Return O nly the Fa mily (Last ) Name.
	8251	flags:(opt ional) Fla gs to cont rols proce ssing. Pos sible valu es are:
	8252	C—If the “ F” format is used, r eturn a Co mma betwee n the Fami ly (Last) and Given (First) Na mes. Other wise, the Family (La st) Name a nd the Giv en (First) Name are separated by a space . (Ignored if the “F ” format i s not used .)
	8253	D—Return t he Degree.
	8254	Dc—Return the Degree preceded by a comma and space .
	8255	L#—Truncat e the retu rned name to a maxim um Length of # chara cters, whe re # is an integer b etween 1 a nd 256. Se e the “Det ails” sect ion for a descriptio n of the p runing alg orithm.
	8256	M—Return t he name in Mixed cas e, with th e first le tter of ea ch name co mponent ca pitalized.
	8257	P—Return t he Prefix.
	8258	S—Standard ize the na me compone nts before building formatted name.
	8259	Xc—Precede the Suffi X with a c omma and s pace.
	8260	Output:ret urns:Retur ns the for matted nam e.
	8261
	8262	Details
	8263	If the L# flag is us ed, and th e resultin g name is longer tha n #, the f ollowing p runing alg orithm is performed to shorten the name:
	8264	Drop Degre e.
	8265	Drop Prefi x.
	8266	Truncate M iddle Name from the right-most position until only the initi al charact er is left .
	8267	Drop suffi x.
	8268	Truncate G iven Name from the r ight-most position u ntil only the initia l characte r is left.
	8269	Truncate F amily Name from the right-most position.
	8270	Truncate t he name fr om the rig ht.
	8271	Examples
	8272	Example 1
	8273	Suppose th e MYNAME a rray conta ins the fo llowing el ements:
	8274	MYNAME(“PR EFIX”)=“MR .”
	8275	MYNAME(“GI VEN”)=“SIX TY”
	8276	MYNAME(“MI DDLE”)=“K. ”
	8277	MYNAME(“FA MILY”)=“XU USER”
	8278	MYNAME(“SU FFIX”)=“JR ”
	8279	MYNAME(“DE GREE”)=“PH D”
	8280
	8281	Then calls to the $$ NAMEFMT^XL FNAME API returns th e name as follows:
	8282	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”)
	8283
	8284	>W X
	8285	XUUSER SIX TY K. JR
	8286
	8287	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“C”)
	8288
	8289	>W X
	8290	XUUSER,SIX TY K. JR
	8291
	8292	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“CS”)
	8293
	8294	>W X
	8295	XUUSER,SIX TY K JR
	8296
	8297	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“CSD” )
	8298
	8299	>W X
	8300	XUUSER,SIX TY K JR PH D
	8301
	8302	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“CDcX c”)
	8303
	8304	>W X
	8305	XUUSER,SIX TY K., JR, PHD
	8306
	8307	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“CSL1 2”)
	8308
	8309	>W X
	8310	XUUSER,SI K
	8311
	8312	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“F”,“CMD” )
	8313
	8314	>W X
	8315	Xuuser,Six ty K. Jr P hD
	8316
	8317	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”)
	8318
	8319	>W X
	8320	SIXTY K. X UUSER JR
	8321
	8322	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“D”)
	8323
	8324	>W X
	8325	SIXTY K. X UUSER JR P HD
	8326
	8327	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“Dc”)
	8328
	8329	>W X
	8330	SIXTY K. X UUSER JR, PHD
	8331
	8332	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“P”)
	8333
	8334	>W X
	8335	MR. SIXTY K. XUUSER JR
	8336
	8337	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“Xc”)
	8338
	8339	>W X
	8340	SIXTY K. X UUSER, JR
	8341
	8342	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“PDcX c”)
	8343
	8344	>W X
	8345	MR. SIXTY K. XUUSER, JR, PHD
	8346
	8347	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“PDcX cM”)
	8348
	8349	>W X
	8350	Mr. Sixty K. Xuuser, Jr, PhD
	8351
	8352	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“S”)
	8353
	8354	>W X
	8355	SIXTY K XU USER JR
	8356
	8357	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“G”,“SL12 ”)
	8358
	8359	>W X
	8360	SI K XUUSE R
	8361
	8362	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“O”)
	8363
	8364	>W X
	8365	XUUSER
	8366
	8367	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“O”,“S”)
	8368
	8369	>W X
	8370	XUUSER
	8371
	8372	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“O”,“M”)
	8373
	8374	>W X
	8375	Xuuser
	8376
	8377	>S X=$$NAM EFMT^XLFNA ME(.MYNAME ,“O”,“L3”)
	8378
	8379	>W X
	8380	XU
	8381
	8382	Example 2
	8383	If an entr y in the N AME COMPON ENTS file (#20) stor es the com ponents of a name st ored in th e NAME fie ld (#.01) of record number 32 in the NEW PERSON fi le (#200), and the d ata in the correspon ding recor d in the N AME COMPON ENTS file (#20) is:
	8384	FILE = 200
	8385	FIELD = .0 1
	8386	IENS = “32 ,”
	8387	PREFIX = “ MR.”
	8388	GIVEN NAME = “SIXTY”
	8389	MIDDLE NAM E = “K.”
	8390	FAMILY NAM E = “XUUSE R”
	8391	SUFFIX = “ JR”
	8392	DEGREE = “ PHD”
	8393
	8394	You can se t:
	8395	MYNAME(“FI LE”)=200
	8396	MYNAME(“FI ELD”)=.01
	8397	MYNAME(“IE NS”)=“32,”
	8398
	8399	Then call the $$NAME FMT^XLFNAM E API, as in Example 1, to ret urn the na me in vari ous format s.
	8400	STDNAME^XL FNAME(): N ame Standa rdization Routine
	8401	Reference Type:Suppo rted
	8402	Category:N ame Standa rdization
	8403	ICR #:3065
	8404	Descriptio n:This API parses a name and c onverts it into the following standard f ormat:
	8405	Family_nam e,Given_na me<space>M iddle_name <space>Suf fix(es)
	8406	A name in standard f ormat is e ntirely in uppercase , and cont ains no Ar abic numer als. The F amily_name (last nam e) portion of a stan dard name appears to the left of the com ma and con tains no s paces and no punctua tion excep t hyphens (-). The o ther parts of a stan dard name (the porti on to the right of t he comma) contain no punctuati on except for hyphen s and spac es. NMI an d NMN are not used f or the Mid dle_name.
	8407	STDNAME^XL FNAME opti onally ret urns in an array the component parts of the name. It also op tionally r eturns inf ormation i n an array about pos sible prob lems encou ntered dur ing the co nversion o f the name to standa rd form an d the pars ing of the name into its compo nent parts .
	8408	Format:STD NAME^XLFNA ME(.name[, flags][,.a udit])
	8409	Input Para meters:.na me:(requir ed) NAME i s the name to be con verted to standard f ormat. It is assumed that the name is in the gener al format:
	8410	Family_nam e,Given_na me(s) Midd le_name Su ffix(es)
	8411	If the “F” flag is n ot used, a nd the nam e contains no comma, it is ass umed the n ame is in the genera l format:
	8412	Given_name (s) Middle _name Fami ly_name Su ffix(es)
	8413	The standa rd form of the name is returne d in the N AME variab le. If the “C” flag is passed in, the co mponents o f the name are retur ned in nod es descend ent from N AME. (See the “Outpu t Paramete rs” sectio n below.)
	8414	flags:(opt ional) Fla gs to cont rol proces sing. Poss ible value s are:
	8415	C—Return n ame compon ents in th e NAME arr ay. (See t he “Output Parameter s” section below.)
	8416	F—If the n ame passed in the NA ME input p arameter d oes not co ntain a co mma, assum e it is th e Family N ame only. For exampl e, if the name input is “ST US ER”, retur n the name as “STUSE R” instead of “USER, ST”.
	8417	G—Do not r eturn AUDI T(“GIVEN”) even if t he Given N ame is mis sing.
	8418	P—Remove t ext in par entheses ( ), bracke ts [ ], or braces { } from the name. If such text is actuall y removed, return AU DIT(“STRIP ”).
	8419	.audit:(op tional) If provided, this is a n array th at STDNAME ^XLFNAME r eturns if there are any ambigu ities or p ossible pr oblems in standardiz ing the na me or pars ing the na me into co mponent pa rts. (See the “Outpu t Paramete rs” sectio n below.)
	8420	Output Par ameters:na me:This pa rameter is set to th e name tha t was inpu t converte d to stand ard format .
	8421	If the Fla gs input p arameter c ontains a “C”, the c omponent p arts of th e name are returned in the NAM E array:
	8422	NAME(“FAMI LY) = Fami ly (Last) NameNAME(“ GIVEN”) = Given (Fir st) Name(s )NAME(“MID DLE”) = Mi ddle NameN AME(“SUFFI X”) = Suff ix(es)
	8423	audit:If t his parame ter is set to the or iginal nam e that was passed in the Name parameter. In additi on, if the re were an y problems in the in terpretati on of the Name being standardi zed, desce ndants of Audit are set:
	8424	AUDIT(“sub script”) = “”
	8425	Where “sub script” ca n be any o ne of the following:
	8426	AUDIT(“FAM ILY”)—The Family Nam e starts w ith ST. (T he period and space are remove d from the Family Na me. For ex ample, the name “ST. USER” is converted to “STUSER ”.)
	8427	AUDIT(“GIV EN”)—Retur ned if the re is no G iven Name and the “G ” flag is not passed .
	8428	AUDIT(“MID DLE”)—Retu rned if th ere are th ree or mor e names be tween the first comm a and the Suffix(es) . (All nam e parts ex cept the l ast are as sumed to b e part of the Given Name. Only the last part is as sumed to b e the Midd le Name.)
	8429	AUDIT(“NM” )—Returned if NMI or NMN appea rs to be u sed as the Middle Na me. (NMI a nd NMN are removed f rom the st andard nam e, and the Middle Na me compone nt is retu rned as nu ll.)
	8430	AUDIT(“NOT E”)—Return ed if the name appea rs to cont ain a note or flag t hat may no t actually be part o f the name . For exam ple, the n ame starts with “C-” or “EEE,” or has “F EE” at the end.
	8431	AUDIT(“NUM BER”)—Retu rned if a name part (other tha n a valid numeric Su ffix) cont ains a num ber.
	8432	AUDIT(“PER IOD”)—Retu rned if pe riods were removed.
	8433	AUDIT(“PUN C”)—Return ed if punc tuation wa s removed.
	8434	AUDIT(“SPA CE”)—Retur ned if spa ces were r emoved fro m the Fami ly Name.
	8435	AUDIT(“STR IP”)—Retur ned if tex t in paren theses ( ) , brackets [ ], or b races { } were remov ed from th e Name. (T his is don e only if the “P” fl ag is pass ed.)
	8436	AUDIT(“SUF FIX”)—Retu rned if:
	8437	Suffix(es) are found immediate ly to the left of th e 1st comm a.
	8438	I, V, or X , and noth ing else e xcept vali d suffixes , appear i mmediately after the Given Nam e. (It is interprete d as the M iddle Name .)
	8439	The name i mmediately after the Given Nam e appears to be a no n-numeric suffix (ex cept I, V, and X), a nd everyth ing after that also appear to be suffixe s. (It is assumed th ere are a Given Name and Suffi x(es), but no Middle Name.)
	8440	M.D. or M D is found at the en d of the n ame, or be fore any v alid suffi xes at the end of th e name. (I t is assum ed that M and D are initials i n the Give n or Middl e Name rat her than a Suffix.)
	8441	The name p art before any recog nizable su ffixes is more than one charac ter in len gth and do es not con tain any v owels or Y . It is in terpreted as a suffi x.
	8442	Suffix is found betw een commas immediate ly after t he Family Name.
	8443
	8444	Details
	8445	Standard N ame
	8446	In forming the stand ard name, the follow ing change s are made :
	8447	The name i s converte d to upper case.
	8448	In the Fam ily Name:
	8449	Semicolons (;) and c olons (:) are conver ted to hyp hens (-).S paces and all other punctuatio n except h yphens are removed.
	8450	Spaces and all other punctuati on except hyphens ar e removed.
	8451	In the oth er name pa rts (Given Name, Mid dle Name, and Suffix ).
	8452	Semicolon, colons, c ommas (,), and perio ds (.) are converted to spaces .Spaces an d all othe r punctuat ion except hyphens a re removed .
	8453	All punctu ation exce pt hyphens and space s are remo ved.
	8454	Hyphens an d spaces a t the begi nning and end of the name are removed.
	8455	Two or mor e consecut ive hyphen s/spaces a re replace d with a s ingle hyph en/space.
	8456	Any suffix es immedia te precedi ng the com ma are mov ed to the end.
	8457	The suffix es indicat ing birth positions 1st, 2nd, 3rd, ..., 10th are c onverted t o their Ro man numera l equivale nts I, II, III, … X.
	8458	DR immedia tely after the comma (or if th ere is no comma, at the beginn ing of the name), is assumed t o be a suf fix and mo ved to the end of th e name.
	8459	Any suffix es between two comma s immediat e after th e Family N ame are mo ved to the end of th e name.
	8460	NMI or NMN used as a Middle Na me is dele ted.
	8461	Component Parts Name
	8462	In forming the compo nent parts of the na me, only t he followi ng changes are made:
	8463	The name c omponent i s converte d to upper case.
	8464	In the Fam ily Name, semicolons (;) and c olons (:) are conver ted to hyp hens (-).
	8465	In the oth er name pa rts (Given Name, Mid dle Name, and Suffix ), semicol ons, colon s, and com mas (,) ar e converte d to space s.
	8466	Hyphens an d spaces a t the begi nning and end of the name are removed.
	8467	Two or mor e consecut ive hyphen s/spaces a re replace d with a s ingle hyph en/space.
	8468	A Middle N ame of NMI or NMN is changed t o null.
	8469	Spaces aft er periods are remov ed.
	8470	Accent gra ves (`) an d carets ( ^) are rem oved.
	8471	In parsing the name into its c omponent p arts, if t he name co ntains a c omma or th e “F” flag is passed , STDNAME^ XLFNAME lo oks for su ffixes imm ediately t o the left of the fi rst comma, and at th e very end of the na me. The su ffixes it recognizes are 1ST t hrough 10T H, JR, SR, DR, MD, E SQ, DDS, R N, ARNP, D O, PA, and Roman num erals I th rough X.
	8472	NOTE: The ARNP, DO, and PA suf fixes were added wit h Kernel p atch XU8. 0535.
	8473	If a name part befor e any reco gnizable s uffixes is more than one chara cter in le ngth, and contains n o vowel or ‘Y’, it i s also ass umed to be a suffix. The Name Standardiz ation look s for the DR suffix immediatel y after th e first co mma, and f or any suf fix betwee n two comm as immedia tely after the Famil y Name. Th e portion of the nam e to the l eft of the comma, le ss any suf fixes, is assumed to be the Fa mily Name.
	8474	After STDN AME^XLFNAM E accounts for all S uffixes, i t looks at the porti on of the name after the comma . It assum es that th e first sp ace-delimi ted piece is the Giv en Name. I f any othe r pieces a re left, t he last on e (rightmo st) is ass umed to be the Middl e Name, an d anything else is a ppended to the end o f the Give n Name.
	8475	If the nam e contains no comma, and the “ F” flag is not passe d, STDNAME ^XLFNAME l ooks for s uffixes at the very end of the name. The last spac e-delimite d piece be fore any s uffixes is assumed t o be the F amily Name . The firs t space-de limited pi ece is ass umed to be the Given Name. If any other pieces are left, the last one (rightmost ) is assum ed to be t he Middle Name, and anything e lse is app ended to t he end of the Given Name.
	8476	Example
	8477	In this ex ample, the MYNAME va riable is set to the name to b e standard ized. The “C” flag i ndicates t hat the na me compone nts should be return ed in the MYNAME arr ay, and th e “P” flag indicates that pare nthetical text shoul d be remov ed from th e name. ST DNAME^XLFN AME sets M YAUD to or iginal nam e passed i n and sets nodes in the MYAUD array to f lag change s and poss ible probl ems.
	8478	Figure 88: STDNAME^X LFNAME API —Example
	8479	>S MYNAME= “XUUSER,FI FTY A. B. 2ND (TEST) ”
	8480	>D STDNAME ^XLFNAME(. MYNAME,“CP ”,.MYAUD)
	8481
	8482	>ZW MYNAME
	8483	MYNAME=XUU SER,FIFTY A B II
	8484	MYNAME(“FA MILY”)=XUU SER
	8485	MYNAME(“GI VEN”)=FIFT Y A.
	8486	MYNAME(“MI DDLE”)=B.
	8487	MYNAME(“SU FFIX”)=2ND
	8488
	8489	>ZW MYAUD
	8490	MYAUD=XUUS ER,FIFTY A . B. 2ND ( TEST)
	8491	MYAUD(“MID DLE”)=“”
	8492	MYAUD(“PER IOD”)=“”
	8493	MYAUD(“SPA CE”)=“”
	8494	MYAUD(“STR IP”)=“”
	8495
	8496	STDNAME^XL FNAME retu rned the s tandard fo rm of the name in MY NAME as XU USER,FIFTY A B II. I t interpre ted FIFTY A. as the given (fir st) name a nd B. as t he middle name. Sinc e this may not be co rrect, MYA UD(“MIDDLE ”) is set. Periods w ere remove d and spac es were re moved to f orm the st andard nam e, therefo re MYAUD(“ PERIOD”) a nd MYAUD(“ SPACE”) we re set. Fi nally, sin ce the par enthetical text (TES T) was rem oved, MYAU D(“STRIP”) was set.
	8497	DELCOM P^X LFNAME2(): Delete Na me Compone nts Entry
	8498	Reference Type:Contr olled Subs cription
	8499	Category:N ame Standa rdization
	8500	ICR #:3066
	8501	Descriptio n:This API deletes a n entry in the NAME COMPONENTS file (#20 ), and opt ionally, t he value o f the poin ter in the source fi le that po ints to th e name com ponents en try.
	8502	NOTE: This API is de signed to be used in the KILL logic for the MUMPS cross-refe rence ment ioned prev iously in the UPDCOM P^XLFNAME2 (): Update Name Comp onents Ent ry API.
	8503	Format:DEL COMP^XLFNA ME2(file,[ .]record,f ield[,ptrf ield])
	8504	Input Para meters:fil e:(require d) The num ber of the file or M ultiple (t he “source file”) th at contain s the name .
	8505	[.]record: (required) The IENS or the Int ernal Entr y Number a rray (that looks lik e the DA a rray) of t he record in the sou rce file t hat contai ns the nam e.
	8506	field:(req uired) The number of the field in the so urce file that conta ins the na me.
	8507	ptrfield:( optional) The number of the po inter fiel d in the s ource file that poin ts to the NAME COMPO NENTS file (#20). On ly if this parameter is passed is the va lue of thi s pointer field dele ted.
	8508	Output:non e.Deletes record.
	8509
	8510	Example
	8511	Suppose th at you hav e a NAME C OMPONENTS file (#20) entry tha t contains the compo nents of a name stor ed in File #1000, Re cord #132, Field #.0 1. Pointer Field #1. 1 of that File #1000 is a poin ter to the NAME COMP ONENTS fil e (#20). T o delete t he entry i n the NAME COMPONENT S file (#2 0), and th e value of the point er field, you can do the follo wing:
	8512	>D DELCOMP ^XLFNAME(1 000,132,.0 1,1.1)
	8513
	8514	UPDCOMP^XL FNAME2(): Update Nam e Componen ts Entry
	8515	Reference Type:Contr olled Subs cription
	8516	Category:N ame Standa rdization
	8517	ICR #:3066
	8518	Descriptio n:This API updates a n entry in the NAME COMPONENTS file (#20 ). Optiona lly, the p ointer in the source file that points to the name components entry is also updat ed.
	8519	This API i s designed to be use d in the S ET logic o f a MUMPS cross-refe rence on t he name fi eld in a s ource file , to keep the name f ield and t he associa ted name c omponents in sync. F or an exam ple of its use, see the ANAME index in t he INDEX f ile (#.11) . The ANAM E index is a MUMPS c ross-refer ence on th e .01 NAME field of the NEW PE RSON file (#200). If an entry’ s NAME fie ld is edit ed, the AN AME cross- reference updates th e associat ed entry i n the NAME COMPONENT S file (#2 0).
	8520	NOTE: Exis ting MUMPS cross-ref erences on the NAME COMPONENTS file (#20 ) already exist to u pdate the associated name fiel d on the s ource file if the co mponents a re edited.
	8521	Format:UPD COMP^XLFNA ME2(file,[ .]record,f ield,[.]na me[,ptrfie ld][,ptrva l])
	8522	Input Para meters:fil e:(require d) The num ber of the file or M ultiple (t he “source file”) th at contain s the name .
	8523	[.]record: (required) The IENS or the Int ernal Entr y Number a rray (that looks lik e the DA a rray) of t he record in the sou rce file t hat contai ns the nam e.
	8524	field:(req uired) The number of the field in the so urce file that conta ins the na me.
	8525	[.]name:(r equired) A n array th at contain s the comp onent part s of the n ame to sto re in the NAME COMPO NENTS file (#20) ent ry:
	8526	NAME(“FAMI LY) = Fami ly Name (r equired)NA ME(“GIVEN” ) = Given Name(s) (o ptional)NA ME(“MIDDLE ”) = Middl e Name(s) (optional) NAME(“SUFF IX”) = Suf fix(es) (o ptional)NA ME(“PREFIX ”) = Prefi x (optiona l)NAME(“NO TES”) = op tional fre e text str ing
	8527	Alternativ ely, a nam e in stand ard format can be pa ssed in th e NAME inp ut paramet er. If the NAME inpu t paramete r has no d escendants (that is, $D(NAME)= 1), UPDCOM P^XLFNAME2 makes a c all to the NAMECOMP^ XLFNAME(): Component Parts fro m Standard Name API to build t he NAME ar ray for yo u.
	8528	ptrfield:( optional) The number of the po inter fiel d in the s ource file that poin ts to the NAME COMPO NENTS file (#20). On ly if this parameter is passed is the va lue of thi s pointer field upda ted with t he entry n umber of t he record in the NAM E COMPONEN TS file (# 20) that w as added o r edited.
	8529	ptrval:(op tional) Th e current value of t he pointer field spe cified by the PTRFIE LD input p arameter. This param eter can b e used to save proce ssing time . If both PTRFIELD a nd PTRVAL are passed , the poin ter field is updated only if t his value is differe nt from th e entry nu mber of th e record i n the NAME COMPONENT S file (#2 0) that wa s added or edited.
	8530	Output:ret urns:Updat ed entry i n the NAME COMPONENT S file (#2 0).
	8531
	8532	Example
	8533	Suppose th e .01 fiel d of File #1000 cont ains a per son’s name , and the component parts of t he name in entry 132 should be updated a s follows:
	8534	Family (la st) name: XUUSER
	8535	Given (fir st) name: FIFTY HENR Y
	8536	Middle nam e: A.
	8537	Suffix: JR .
	8538	Field #1.1 is define d as a poi nter to th e NAME COM PONENTS fi le (#20) a nd has a v alue of 42 , the IEN of a recor d in the N AME COMPON ENTS file (#20). To update the NAME COMP ONENTS fil e (#20) wi th this na me, you ca n do the f ollowing:
	8539	Figure 89: UPDCOMP^X LFNAME2 AP I—Example
	8540	>S MYNAME( “FAMILY”)= “XUUSER”
	8541	>S MYNAME( “GIVEN”)=“ FIFTY HENR Y”
	8542	>S MYNAME( “MIDDLE”)= “A.”
	8543	>S MYNAME( “SUFFIX”)= “JR.”
	8544
	8545	>D UPDCOMP ^XLFNAME2( 1000,132,. 01,.MYNAME ,1.1,42)
	8546
	8547	If there i s an entry in the NA ME COMPONE NTS file ( #20) that correspond s to File #1000, Fie ld #.01, I EN #132, t hat entry is updated with the name compo nents pass ed in the MYNAME arr ay. Otherw ise, a new entry is added to t he name co mponents w ith this i nformation .
	8548	If the ent ry in the name compo nents that was updat ed or adde d is recor d #42, no change is made to th e value of the point er field # 1.1, since 42 was pa ssed in th e 6th para meter.
	8549	MUMPS cros s-referenc es on the NAME COMPO NENTS file (#20) upd ates the n ame in the Field #.0 1 of File #1000 to “ XUUSER,FIF TY HENRY A JR” if it does not already co ntain that name.
	8550
	8551
	8552	National P rovider Id entifier ( NPI): Deve loper Tool s
	8553	Applicatio n Programm ing Interf ace (API)
	8554	The follow ing are Na tional Pro vider Iden tifier (NP I) APIs av ailable fo r develope rs. These APIs are d escribed b elow.
	8555	$$CHKDGT^X USNPI(): V alidate NP I Format
	8556	Reference Type:Contr olled Subs cription
	8557	Category:N ational Pr ovider Ide ntifier (N PI)
	8558	ICR #:4532
	8559	Descriptio n:This ext rinsic fun ction vali dates the format of a National Provider Identifier (NPI) num ber. It ch ecks the f ollowing:
	8560	NPI is num eric.
	8561	Length of the Number (must be 10-digits) .
	8562	Check Digi t is Valid .
	8563	This API w as added w ith Kernel patch XU* 8.0*410.
	8564	Format:$$C HKDGT^XUSN PI(xusnpi)
	8565	Input Para meters:xus npi:(requi red) The 1 0-digit Na tional Pro vider Iden tifier (NP I) number to validat e. No defa ult.
	8566	Output:ret urns:Retur ns:
	8567	1—If check digit is valid. The NPI numbe r must be 10-digits long.
	8568	0—If check digit is not valid.
	8569
	8570	Examples
	8571	Example 1
	8572	The follow ing exampl e shows th e result w hen checki ng a valid NPI:
	8573	>W $$CHKDG T^XUSNPI(1 234567893)
	8574	1
	8575
	8576	Example 2
	8577	The follow ing exampl e shows th e result w hen checki ng an inva lid NPI (n ot 10 digi ts):
	8578	>W $$CHKDG T^XUSNPI(1 23456789)
	8579	0
	8580
	8581	$$NPI^XUSN PI(): Get NPI from F iles #200 or #4
	8582	Reference Type:Contr olled Subs cription
	8583	Category:N ational Pr ovider Ide ntifier (N PI)
	8584	ICR #:4532
	8585	Descriptio n:This ext rinsic fun ction retr ieves the National P rovider Id entifier ( NPI) and r elated uti lities fro m the NEW PERSON (#2 00) or INS TITUTION ( #4) files. This API was added with Kerne l patch XU 8.0410.
	8586	Format:$$N PI^XUSNPI( xusqi,xusi en[,xusdat e])
	8587	Input Para meters:xus qi:(requir ed) The Qu alified Id entifier f or the NPI . For exam ple: Indiv idual_ID o r Organiza tion_ID. N o default.
	8588	xusien:(re quired) Th e Internal Entry Num ber (IEN) from the N EW PERSON (#200) or INSTITUTIO N (#4) fil es. No def ault.
	8589	xusdate:(o ptional) A date of i nterest. D efaults to “Today.”
	8590	Output:ret urns:Retur ns any of the follow ing string s:
	8591	NPI^Effect iveDate^St atus—If Na tional Pro vider Iden tifier (NP I) exists.
	8592	0—If NPI d oes not ex ist.
	8593	-1^ErrorMe ssage—If i nvalid xus qi or xusi en.
	8594
	8595	Examples
	8596	Example 1
	8597	The follow ing exampl e uses the following file data :
	8598	Individual _ID = NEW PERSON fil e (#200)
	8599	NPI = 9876 543213
	8600	EffectiveD ate = 3061 108.123651
	8601	Status = A ctive
	8602
	8603	>W $$NPI^X USNPI(“Ind ividual_ID ”,82)
	8604	9876543213 ^3061108.1 23651^Acti ve
	8605
	8606	Example 2
	8607	The follow ing exampl e uses the following file data :
	8608	Organizati on_ID = IN STITUTION file (#4)
	8609	NPI = 1111 111112
	8610	EffectiveD ate = 3070 122
	8611	Status = A ctive
	8612
	8613	>W $$NPI^X USNPI(“Org anization_ ID”,1)
	8614	1111111112 ^3070122^A ctive
	8615
	8616	$$QI^XUSNP I(): Get P rovider En tities
	8617	Reference Type:Contr olled Subs cription
	8618	Category:N ational Pr ovider Ide ntifier (N PI)
	8619	ICR #:4532
	8620	Descriptio n:This ext rinsic fun ction retr ieves all qualified provider e ntities fo r a Nation al Provide r Identifi er (NPI) i dentifier. This API was added with Kerne l patch XU 8.0410.
	8621	Format:$$Q I^XUSNPI(x usnpi)
	8622	Input Para meters:xus npi:(requi red) The N ational Pr ovider Ide ntifier (N PI) identi fier. No d efault.
	8623	Output:ret urns:Retur ns either of the fol lowing str ings:
	8624	QualifiedI dentifier^ IEN^Effect iveDate^St atus—Natio nal Provid er Identif ier (NPI) exists. If more than one recor d is found , they are separated by “;”.
	8625	0—Qualifie d NPI does not exist .
	8626
	8627	Examples
	8628	Example 1
	8629	The follow ing exampl e uses the following file data :
	8630	Individual _ID = NEW PERSON fil e (#200)
	8631	IEN = 82
	8632	EffectiveD ate = 3061 108.123651
	8633	Status = A ctive
	8634
	8635	>W $$QI^XU SNPI(98765 43213)
	8636	Individual _ID^82^306 1108.12365 1^Active;
	8637
	8638	Example 2
	8639	The follow ing exampl e uses the following file data :
	8640	Organizati on_ID = in stitution file (#4)
	8641	IEN = 1
	8642	EffectiveD ate = 3070 122
	8643	Status = A ctive
	8644
	8645	>W $$QI^XU SNPI(11111 11112)
	8646	Organizati on_ID^1^30 70122^Acti ve;
	8647
	8648	$$TAXIND^X USTAX(): G et Taxonom y Code fro m File #20 0
	8649	Reference Type:Contr olled Subs cription
	8650	Category:N ational Pr ovider Ide ntifier (N PI)
	8651	ICR #:4911
	8652	Descriptio n:This ext rinsic fun ction retr ieves the taxonomy c ode for a given reco rd in the NEW PERSON file (#20 0). This A PI was add ed with Ke rnel patch XU8.041 0.
	8653	Format:$$T AXIND^XUST AX(xuien)
	8654	Input Para meters:xui en:(requir ed) This i s the Inte rnal Entry Number (I EN) of the record in the NEW P ERSON file (#200). N o default.
	8655	Output:ret urns:Retur ns either of the fol lowing str ings:
	8656	TaxonomyX1 2Code^Taxo nomyIEN—Ta xonomy exi sts.
	8657	^—Taxonomy does not exist.
	8658
	8659	Example
	8660	The follow ing exampl e uses the following file data :
	8661	Taxonomy X 12 code of the recor d in the N EW PERSON file (#200 ) = 2086S0 105
	8662	Taxonomy I EN from th e PERSON C LASS file (#8932.1) = 900
	8663
	8664	>W $$TAXIN D^XUSTAX(8 2)
	8665	2086S0105X ^900
	8666
	8667	$$TAXORG^X USTAX(): G et Taxonom y Code fro m File #4
	8668	Reference Type:Contr olled Subs cription
	8669	Category:N ational Pr ovider Ide ntifier (N PI)
	8670	ICR #:4911
	8671	Descriptio n:This ext rinsic fun ction retr ieves the taxonomy c ode for a given reco rd in the INSTITUTIO N file (#4 ). This AP I was adde d with Ker nel patch XU8.0410 .
	8672	Format:$$T AXORG^XUST AX(xuien)
	8673	Input Para meters:xui en:(requir ed) This i s the Inte rnal Entry Number (I EN) of the record in the INSTI TUTION fil e (#4). No default.
	8674	Output:ret urns:Retur ns either of the fol lowing str ings:
	8675	TaxonomyX1 2Code^Taxo nomyIEN—Ta xonomy exi sts.
	8676	^—Taxonomy does not exist.
	8677
	8678	Example
	8679	The follow ing exampl e uses the following file data :
	8680	Taxonomy X 12 code of the recor d in the I NSTITUTION file (#4) = 3902000 00X
	8681	Taxonomy I EN from th e PERSON C LASS file (#8932.1) = 144
	8682
	8683	>W $$TAXOR G^XUSTAX(2 )
	8684	390200000X ^144
	8685
	8686
	8687	Operating System (OS ) Interfac e: Develop er Tools
	8688	Overview
	8689	Kernel and Kernel To olkit prov ides sever al utiliti es to work with the underlying operating system. I n addition , Kernel’s ^%ZOSF gl obal holds operating system-de pendent lo gic so tha t applicat ion progra ms can be written in dependentl y of any s pecific op erating sy stem. Each CPU or no de in a sy stem shoul d have its own copy of the ^%Z OSF global ; the ^%ZO SF global should not be transl ated.
	8690	Direct Mod e Utilitie s
	8691	>D ^%ZTBKC : Global B lock Count
	8692	You can co unt the da ta blocks in a globa l using th e direct m ode utilit y ^%ZTBKC. An entire global or a subscri pted secti on can be measured, such as ^D IC or ^DIC (9.2). The re is a co rrespondin g option t hat can be used from the Progr ammer Opti ons menu, called the Global Bl ock Count option [XU BLOCK COU NT].
	8693	REF: For m ore inform ation on t he XU BLOC K COUNT, s ee Section 28, “Misc ellaneous Programmer Tools,” i n the Kern el Systems Managemen t Guide.
	8694	>D ^ZTMGRS ET: Update ^%ZOSF No des
	8695	This direc t mode uti lity is on ly availab le from th e manager’ s account. It is ord inarily ru n during K ernel inst allations to initial ize Kernel in the ma nager’s ac count. It can be use d at a lat er time, h owever, to update an account’s ^%ZOSF no des with n ew UCI and Volume Se t informat ion. The ^ %ZOSF node s that ^ZT MGRSET upd ates are:
	8696	^%ZOSF(“MG R”)
	8697	^%ZOSF(“PR OD”)
	8698	^%ZOSF(“VO L”)
	8699	An example of a use for re-run ning ^ZTMG RSET would be when c reating a new print, compute, file, or s hadow serv er by copy ing an exi sting serv er’s accou nt. Althou gh Kernel is already set up in the copie d account, the new s erver’s UC I and Volu me Set ^%Z OSF nodes would need to be upd ated from their old values to the values needed fo r the new server. Re -running ^ ZTMGRSET a llows thes e values t o be updat ed.
	8700	Applicatio n Programm ing Interf ace (API)
	8701	Several AP Is are ava ilable for developer s to work with the o perating s ystem. The se APIs ar e describe d below.
	8702	^%ZOSF(): Operating System-dep endent Log ic Global
	8703	The ^%ZOSF global ho lds operat ing system -dependent logic so that appli cation pro grams can be written independe ntly of an y specific operating system.
	8704	Most of th e nodes co ntain logi c that mus t be execu ted to ret urn a valu e, for exa mple:
	8705	X ^%ZOSF(“ SS”)
	8706	Those pref aced with one asteri sk in Tabl e 29, howe ver, are r eference v alues. For example, to WRITE t he operati ng system, use:
	8707	W ^%ZOSF(“ OS”)
	8708	The nodes prefaced w ith two as terisks in Table 29 should be used with the DO com mand, as i n the foll owing:
	8709	>D @^%ZOSF (“ERRTN”)
	8710	Table Key:
	8711	*indicates those nod es that ho ld referen ce values.
	8712	**indicate s those no des that a re invoked with a DO statement (D).
	8713	Table 29: ^%ZOSF API —Global no des
	8714	Node
	8715	Descriptio n
	8716	ACTJ
	8717	Return in Y the numb er of acti ve jobs on the syste m.
	8718	AVJ
	8719	Return in Y the numb er of jobs that can be started . The numb er of avai lable jobs is the ma ximum numb er less th e number o f active j obs.
	8720	BRK
	8721	Allow the user to br eak the ru nning of a routine.
	8722	DEL
	8723	Delete the routine n amed in X from the U CI.
	8724	EOFF
	8725	Turn off e cho to the $I device .
	8726	EON
	8727	Turn on ec ho to the $I device.
	8728	EOT
	8729	Returns Y = 1 if Mag tape end-o f-tape mar k is detec ted.
	8730	**ERRTN
	8731	This node is set to the name o f the rout ine that s hould be u sed to rec ord errors . For most systems t his is the KERNEL er ror record ing routin e (%ZTER):
	8732	>D @^%ZOSF (“ERRTN”)
	8733	To initial ly set the Error Tra p:
	8734	>S X=^%ZOS F(“ERRTN”) ,@^%ZOSF(“ TRAP”)
	8735	ETRP
	8736	Obsolete.
	8737	GD
	8738	Display th e global d irectory.
	8739	GSEL
	8740	Returns th e user’s s election o f globals as follows :
	8741	^UTILITY($ J,“global name”)
	8742	NOTE: Thi s is only supported for Caché at this ti me.
	8743	JOBPARAM
	8744	When passe d the job in X, retu rns the UC I for that job in Y. It determ ines wheth er the job is valid on the sys tem.
	8745	LABOFF
	8746	Turn off e cho to the IO device .
	8747	LOAD
	8748	Load routi ne X into @(DIF_”XCN P,0)”.
	8749	LPC
	8750	Returns in Y the lon gitudinal parity che ck of the string in X.
	8751	MAGTAPE
	8752	Sets the % MT local v ariable to hold magt ape functi ons. Issue the backs pace comma nd as foll ows:
	8753	>W @%MT(“B S”)
	8754	The full l ist of fun ctions are :
	8755	“BS”—Back Space
	8756	“FS”—Forwa rd Space
	8757	“WTM”—WRIT E Tape Mar k
	8758	“WB”—WRITE Block
	8759	“REW”—Rewi nd
	8760	“RB”—READ Block
	8761	“REL”—READ Label
	8762	“WHL”—WRIT E HDR Labe l
	8763	“WEL”—WRIT E EOF Labe l
	8764	MAXSIZ
	8765	For M/SQL- VAX only. Sets the p artition s ize to X.
	8766	*MGR
	8767	Holds the name of th e MGR acco unt (UCI, Volume Set ).
	8768	MTBOT
	8769	Returns Y = 1 if the magtape i s at BOT.
	8770	MTERR
	8771	Returns Y = 1 if a m agtape err or is dete cted.
	8772	MTONLINE
	8773	Returns Y = 1 if the magtape i s online.
	8774	MTWPROT
	8775	Returns Y = 1 if the magtape i s WRITE Pr otected.
	8776	NBRK
	8777	Do not all ow the use r to break a routine .
	8778	NO-PASSALL
	8779	Sets devic e $I to in terpret ta bs, carria ge returns , line fee ds, or con trol chara cters (nor mal text m ode).
	8780	NO-TYPE-AH EAD
	8781	Turn off t he TYPE-AH EAD for th e device $ I.
	8782	*OS
	8783	In the fir st “^” pie ce, holds the type o f MUMPS (e .g., Caché , VAX DSM, GT.M).
	8784	PASSALL
	8785	Sets devic e $I to pa ss all cod es, allow tabs, carr iage retur ns, and ot her contro l characte rs to be p assed (bin ary transf er).
	8786	PRIINQ
	8787	Returns Y with the c urrent pri ority of t he job.
	8788	PRIORITY
	8789	Sets the p riority of the job t o X (1 is low, 10 is high).
	8790	*PROD
	8791	Holds the name of th e Producti on account (UCI, Vol ume Set).
	8792	PROGMODE
	8793	Returns Y = 1 if the user is i n Programm er mode.
	8794	RD
	8795	Displays t he routine directory .
	8796	RESJOB
	8797	References the opera ting syste m routine for restor ing a job.
	8798	RM
	8799	Sets the $ I width to X charact ers. If X= 0, then th e line in set to no wrap.
	8800	RSEL
	8801	Returns th e user’s s election o f routines as follow s:
	8802	^UTILITY($ J,“routine name”)
	8803	RSUM
	8804	Passes a r outine nam e in X, an d it retur ns the che cksum in Y . Used by CHECK^XTSU MBLD. The second lin e and comm ents are n ot include d in the t otal.
	8805	RSUM1
	8806	Passes a r outine nam e in X, an d it retur ns the che cksum in Y . Used by CHECK1^XTS UMBLD. The second li ne and com ments are not includ ed in the total.
	8807	SAVE
	8808	Saves the code in @( DIE_”XCN,0 )”) as rou tine X.
	8809	SIZE
	8810	Returns Y= size (in b ytes) of t he current routine.
	8811	SS
	8812	Displays t he system status.
	8813	TEST
	8814	Returns $T = 1 if ro utine X ex ists.
	8815	TMK
	8816	Returns Y = 1 if a t ape mark w as detecte d on the l ast READ.
	8817	TRAP
	8818	To set the Error Tra p:
	8819	>S X=“erro r routine” ,@^%ZOSF(“ TRAP”)
	8820	TRMOFF
	8821	Resets ter minators t o normal.
	8822	TRMON
	8823	Turns on a ll control s as termi nators.
	8824	TRMRD
	8825	Returns in Y what te rminated t he last RE AD.
	8826	TYPE-AHEAD
	8827	Allow TYPE -AHEAD for the devic e $I.
	8828	UCI
	8829	Returns Y with the c urrent acc ount (UCI, Volume Se t).
	8830	UCICHECK
	8831	Returns Y’ =“” if X i s a valid UCI name.
	8832	UPPERCASE
	8833	Converts l owercase t o uppercas e. Setting X=“User N ame” retur ns Y=“USER NAME”. Ap plications can gain efficiency by execut ing this n ode rather than perf orming che cks within the appli cation pro gram.
	8834	*VOL
	8835	Contains t he current Volume Se t (CPU) na me.
	8836	XY
	8837	Sets $X=DX and $Y=DY (may not work on al l systems) .
	8838	ZD
	8839	Given X in $H format , returns the printa ble form o f X in Y.
	8840
	8841	$$ACTJ^%ZO SV: Number of Active Jobs
	8842	Reference Type:Suppo rted
	8843	Category:O perating S ystem Inte rface
	8844	ICR #:1009 7
	8845	Descriptio n:This ext rinsic fun ction retu rns the nu mber of ac tive jobs in the sco pe of this process. It is the same as ^% ZOSF(“ACTJ ”).
	8846	Format:$$A CTJ^%ZOSV
	8847	Input Para meters:non e.
	8848	Output:ret urns:Retur ns the num ber of act ive jobs.
	8849
	8850	$$AVJ^%ZOS V: Number of Availab le Jobs
	8851	Reference Type:Suppo rted
	8852	Category:O perating S ystem Inte rface
	8853	ICR #:1009 7
	8854	Descriptio n:This ext rinsic fun ction retu rns a best effort on the numbe r of avail able jobs (i.e., num ber of new jobs that could be started). It is the same as ^% ZOSF(“AVJ” ).
	8855	Format:$$A VJ^%ZOSV
	8856	Input Para meters:non e.
	8857	Output:ret urns:Retur ns the num ber of ava ilable job s.
	8858
	8859	DOLRO^%ZOS V: Display Local Var iables
	8860	Reference Type:Contr olled Subs cription
	8861	Category:O perating S ystem Inte rface
	8862	ICR #:3883
	8863	Descriptio n:This API saves all local var iables. It stores al l local va riables in the globa l storage location s pecified b y the “X” input vari able.
	8864	Format:DOL RO^%ZOSV
	8865	Make sure to perform the follo wing steps before ca lling this API:
	8866	NEW all no n-namespac ed variabl es.
	8867	Set all in put variab les.
	8868	Call the A PI.
	8869	Input Vari ables:X:(r equired) W hen this v ariable is set to an open glob al referen ce, (e.g., ’^XTMP(“Z ZHL”,25,’) , all loca l variable s existent when DOLR O^%ZOSV is called ar e stored i n the loca tion speci fied by th e open glo bal refere nce. These variables , now stor ed in the X-specifie d global l ocation, c an be list ed and exa mined by a pplication developer s.
	8870	Output:ret urns:Local variables are store d in the g lobal spec ified by t he X input variable.
	8871
	8872	Example
	8873	>S X=“^%ZT SK(ZTSKm.3 ,” D DOLRO ^%ZOSV
	8874
	8875	GETENV^%ZO SV: Curren t System I nformation
	8876	Reference Type:Suppo rted
	8877	Category:O perating S ystem Inte rface
	8878	ICR #:1009 7
	8879	Descriptio n:This API returns e nvironment informati on about t he current system.
	8880	Format:GET ENV^%ZOSV
	8881	Input Para meters:non e.
	8882	Output Var iables:Y:R eturns a s tring in t he followi ng format:
	8883	UCI^VOL/DI R^NODE^BOX LOOKUP
	8884
	8885	$$LGR^%ZOS V: Last Gl obal Refer ence
	8886	Reference Type:Suppo rted
	8887	Category:O perating S ystem Inte rface
	8888	ICR #:1009 7
	8889	Descriptio n:This ext rinsic fun ction retu rns the la st global reference.
	8890	Format:$$L GR^%ZOSV
	8891	Input Para meters:non e.
	8892	Output:ret urns:Retur ns the str ing set to the last full globa l referenc e.
	8893
	8894	Example
	8895	>S X=$$LGR ^%ZOSV
	8896
	8897	LOGRSRC^%Z OSV(): Rec ord Resour ce Usage ( RUM)
	8898	Reference Type:Suppo rted
	8899	Category:O perating S ystem Inte rface
	8900	ICR #:1009 7
	8901	Descriptio n:This API records r esource us age in ^XT MP(“KMPR” via the Re source Usa ge Monitor (RUM) sof tware.
	8902	Format:LOG RSRC^%ZOSV (opt,type, status)
	8903	Input Para meters:opt :(required ) Name of Option, Pr otocol, Re mote Proce dure Call (RPC) or H ealth Leve l Seven (H L7). This is a Free Text param eter.
	8904	type:(requ ired) Type of option :
	8905	0—Option
	8906	1—Protocol
	8907	2—Remote P rocedure C all (RPC)
	8908	3—Health L evel Seven (HL7)
	8909	status:(op tional) Re served for future us e.
	8910	Output:ret urns:This API saves RUM-relate d data for each opti on/type in to a file. This file is then d ownloaded weekly to the Capaci ty Plannin g National Database. The data is then av ailable to all sites via the C apacity Pl anning Ser vice VA In tranet Web site.
	8911
	8912	$$OS^%ZOSV : Get Oper ating Syst em Informa tion
	8913	Reference Type:Suppo rted
	8914	Category:O perating S ystem Inte rface
	8915	ICR #:1009 7
	8916	Descriptio n:This ext rinsic fun ction retu rns the un derlying o perating s ystem (e.g ., VMS on OpenVMS, N T on Windo ws, Unix o n Linux). It is only available under Cac hé/OpenVMS M systems .
	8917	Format:$$O S^%ZOSV
	8918	Input Para meters:non e.
	8919	Output:ret urns:Retur ns the und erlying op erating sy stem infor mation (e. g., VMS on OpenVMS, NT on Wind ows, Unix on Linux).
	8920
	8921	Example
	8922	I ^%ZOSF(“ OS”)[“Open M” S Y=$$O S^%ZOSV
	8923
	8924	SETENV^%ZO SV: Set VM S Process Name (Cach é/OpenVMS Systems)
	8925	Reference Type:Suppo rted
	8926	Category:O perating S ystem Inte rface
	8927	ICR #:1009 7
	8928	Descriptio n:This API sets the VMS proces s name. It only has meaning on Caché/Ope nVMS syste ms, otherw ise it jus t quits.
	8929	Format:SET ENV^%ZOSV
	8930	Make sure to perform the follo wing steps before ca lling this API:
	8931	NEW all no n-namespac ed variabl es.
	8932	Set all in put variab les.
	8933	Call the A PI.
	8934	Input Vari ables:X:(r equired) T his is a 1 -15 charac ter name t o be given to the pr ocess at t he VMS lev el.
	8935	Output:non e.
	8936
	8937	SETNM^%ZOS V(): Set V MS Process Name (Cac hé/OpenVMS Systems)
	8938	Reference Type:Suppo rted
	8939	Category:O perating S ystem Inte rface
	8940	ICR #:1009 7
	8941	Descriptio n:This API sets the VMS proces s name. It only has meaning on Caché/Ope nVMS syste ms, otherw ise it jus t quits. I t is the p arameter-p assing ver sion of th e SETENV^% ZOSV: Set VMS Proces s Name (Ca ché/OpenVM S Systems) API.
	8942	Format:SET NM^%ZOSV(n ame)
	8943	Input Para meters:nam e:(require d) This is a 1-15 ch aracter na me to be g iven to th e process at the VMS level.
	8944	Output:non e.
	8945
	8946	T0^%ZOSV: Start RT M easure (Ob solete)
	8947	NOTE: This API is ob solete as of the rel ease of Ke rnel Toolk it patch X T7.3102 and Kernel patch XU* 8.0*425.
	8948	Reference Type:Suppo rted
	8949	Category:O perating S ystem Inte rface
	8950	ICR #:1009 7
	8951	Descriptio n:This API starts RT Measure. The Kernel site para meter flag to enable RT loggin g must be set for th e volume s et. The se tting of t his flag d efines the XRTL vari able. The call to th is API sho uld, thus, include a check for the exist ence of XR TL, such a s the foll owing:
	8952	>D:$D(xrtl ) T0^%ZOSV
	8953	This API s hould be p laced just before a process th at may tak e a few se conds befo re the sys tem respon ds with an other prom pt. If the minimal p ause is at least a h alf second , there is enough va riability to notice changes as the load on the sys tem is inc reased or decreased. There sho uld be no terminal I Os between the T0 st art point and the T1 stop poin t.
	8954	REF: For m ore inform ation on R T measure, see the R esource Us age Monito r (RUM) do cumentatio n, located on the VD L at: http ://www. DOMAIN /vdl/appli cation.asp ?appid=130

	8955	Format:T0^ %ZOSV
	8956	Input Para meters:non e.
	8957	Output Var iables:XRT 0:Output v ariable (s tart time) .
	8958	The T0 cal l sets the XRT0 vari able to th e start ti me. To dis card a sam ple, the X RT0 variab le should be KILLed. Such a KI LL would b e appropri ate if the re is an e xit path b etween the T0 and T1 checkpoin ts that is circuitou s or other wise irrel evant to t he normal execution of the cod e in quest ion.
	8959	NOTE: On C aché syste ms, it onl y records to the nea rest secon d.
	8960
	8961	T1^%ZOSV: Stop RT Me asure (Obs olete)
	8962	NOTE: This API is ob solete as of the rel ease of Ke rnel Toolk it patch X T7.3102 and Kernel patch XU* 8.0*425.
	8963	Reference Type:Suppo rted
	8964	Category:O perating S ystem Inte rface
	8965	ICR #:1009 7
	8966	Descriptio n:This API stops RT Measure. T his API lo gs the ela psed time into the ^ %ZRTL glob al (obsole te). The A PI should include a check for the existe nce of the XRT0 vari able to co nfirm that the start time is a vailable.
	8967	REF: For m ore inform ation on R T measure, see the R esource Us age Monito r (RUM) do cumentatio n, located on the VD L at: http ://www. DOMAIN /vdl/appli cation.asp ?appid=130
	8968	Format:T1^ %ZOSV
	8969	Make sure to perform the follo wing steps before ca lling this API:
	8970	NEW all no n-namespac ed variabl es.
	8971	Set all in put variab les.
	8972	Call the A PI.
	8973	Input Vari ables:XRTN :(required ) Routine name.
	8974	The XRTN v ariable is normally set to the name of t he routine being mon itored via the comma nd:
	8975	>S XRTN=$T (+0)
	8976	To log mor e than one stop poin t in the s ame routin e, a numbe r or other character s can be c oncatenate d (e.g., X RTN_1) so that a sep arate entr y is made in the ^%Z RTL global (obsolete ), since t he global is subscri pted by ro utine name :
	8977	>S:$D(XRT0 ) XRTN=$T( +0) D:$D(X RT0) T1^%Z OSV
	8978	Output:ret urns:Logs elapsed ti me into th e ^%ZRTL g lobal (obs olete)
	8979
	8980	$$VERSION^ %ZOSV(): G et OS Vers ion Number or Name
	8981	Reference Type:Suppo rted
	8982	Category:O perating S ystem Inte rface
	8983	ICR #:1009 7
	8984	Descriptio n:This ext rinsic fun ction retu rns the op erating sy stem versi on number or name.
	8985	Format:$$V ERSION^%ZO SV([flag])
	8986	Input Para meters:fla g:(optiona l) If you pass a val ue of 1, t he operati ng system name is re turned ins tead of th e version number.
	8987	NOTE: The name is as defined b y the vend or and doe s not nece ssarily co rrespond w ith the OS name stor ed in ^%ZO SF(“OS”).
	8988	Output:ret urns:Retur ns the ope rating sys tem versio n number o r name, de pending on the (opti onal) flag input par ameter.
	8989
	8990	Examples
	8991	Example 1
	8992	>W $$VERSI ON^%ZOSV(1 )
	8993
	8994	Cache for OpenVMS/AL PHA V7.x ( Alpha)
	8995
	8996	Example 2
	8997	>W $$VERSI ON^%ZOSV
	8998
	8999	4.1.16
	9000
	9001
	9002	Security K eys: Devel oper Tools
	9003	Overview
	9004	As well as locking o ptions, de velopers c an use sec urity keys within op tions if s ome part o f an optio n requires special s ecurity. O ne example of this i s Kernel’s use of th e ZTMQ key ; it restr icts funct ionality w ithin the Dequeue Ta sk, Requeu e Tasks, a nd Delete Tasks opti ons.
	9005	Key Lookup
	9006	When writi ng code th at checks whether th e current user holds a certain key, do n ot referen ce the SEC URITY KEY file (#19. 1) for thi s informat ion. Inste ad, check the ^XUSEC global. T he most ef ficient ch eck is:
	9007	>I $D(^XUS EC(keyname ,DUZ))
	9008	This is (a nd continu es to be) a supporte d referenc e. The ^XU SEC global is built by a cross -reference on the SE CURITY KEY file (#19 .1).
	9009	Person Loo kup
	9010	If a key i s flagged for Person Lookup, a cross-ref erence on the NEW PE RSON file (#200) is built and maintained to facili tate APIs. It is con structed w ith the le tters “AK” before th e key name . The Prov ider key i s exported with the Person Loo kup flag s et; as a r esult, pro viders can be easily identifie d in this AK.keyname cross-ref erence, at ^VA(200,“ AK.PROVIDE R”,DUZ). S pecificall y, the loo kup would be:
	9011	>S DIC=“^V A(200,”,DI C()=“AEQ”, D=“AK.PROV IDER” D IX ^DIC
	9012	Applicatio n Programm ing Interf ace (API)
	9013	Several AP Is are ava ilable for developer s to work with secur ity keys. These APIs are descr ibed below .
	9014	DEL^XPDKEY (): Delete Security Key
	9015	Reference Type:Suppo rted
	9016	Category:S ecurity Ke ys
	9017	ICR #:1367
	9018	Descriptio n:This API deletes a security key from t he SECURIT Y KEY file (#19.1). All necess ary indexi ng is perf ormed to m aintain th e ^XUSEC g lobal. The security key is rem oved from all holder s in the N EW PERSON file (#200 ).
	9019	Format:DEL ^XPDKEY(ke y_name)
	9020	Input Para meters:key _name:(req uired) The name of t he securit y key to d elete.
	9021	Output:non e.
	9022
	9023	Example
	9024	>D DEL^XPD KEY(key_na me)
	9025
	9026	$$LKUP^XPD KEY(): Loo k Up Secur ity Key Va lue
	9027	Reference Type:Suppo rted
	9028	Category:S ecurity Ke ys
	9029	ICR #:1367
	9030	Descriptio n:This ext rinsic fun ction look s up a sec urity key by name or by Intern al Entry N umber (IEN ) value. I t returns the securi ty key:
	9031	Name—If ca lled with a security key numbe r.
	9032	IEN—If cal led with a security key name.
	9033	Format:$$L KUP^XPDKEY (key_value )
	9034	Input Para meters:key _value:(re quired) Th e name or IEN of the security key in que stion.
	9035	Output:ret urns:Retur ns the sec urity key:
	9036	Name—If ca lled with a security key numbe r.
	9037	IEN—If cal led with a security key name.
	9038
	9039	Example
	9040	>S value=$ $LKUP^XPDK EY(key_val ue)
	9041
	9042	$$RENAME^X PDKEY(): R ename Secu rity Key
	9043	Reference Type:Suppo rted
	9044	Category:S ecurity Ke ys
	9045	ICR #:1367
	9046	Descriptio n:This ext rinsic fun ction rena mes a secu rity key. All necess ary indexi ng is perf ormed to m aintain th e ^XUSEC g lobal.
	9047	Format:$$R ENAME^XPDK EY(oldname ,newname)
	9048	Input Para meters:old name:(requ ired) Name of securi ty key to be renamed .
	9049	newname:(r equired) N ew name fo r security key.
	9050	Output:ret urns:Retur ns:
	9051	1—Success.
	9052	0—Failure.
	9053
	9054	OWNSKEY^XU SRB(): Ver ify Securi ty Keys As signed to a User
	9055	Reference Type:Suppo rted
	9056	Category:S ecurity Ke ys
	9057	ICR #:3277
	9058	Descriptio n:The XUS KEY CHECK RPC uses t his API to verify if a user ha s a specif ied securi ty key ass igned. The calling r outine sen ds one or a referenc e to a sub scripted a rray and t he API ret urns a sub scripted a rray with the follow ing possib le values:
	9059	1—User own s key.
	9060	0—Key not found.
	9061	The DUZ va riable sho uld be def ined befor e calling this API.
	9062	(This was developed as a Broke r RPC and all RPCs h ave as the first par ameter the return/ou tput param eter.)
	9063	Format:OWN SKEY^XUSRB (ret,list[ ,ien])
	9064	Input Para meters:ret :(required ) Name of the subscr ipted retu rn array. In every A PI that is used as a n RPC, the first par ameter is the return array.
	9065	list:(requ ired) A si ngle value or an inp ut subscri pted array of securi ty keys to be evalua ted.
	9066	ien:(optio nal) The D UZ of a us er for who m you want to check if he/she holds secu rity keys.
	9067	Output:ret ():Returns a subscri pted outpu t array of the input value/sub scripted a rray (i.e. , list) wi th the fol lowing pos sible valu es shown:
	9068	1—User own s key.
	9069	0—Key not found.
	9070
	9071	Examples
	9072	Example 1
	9073	In the fol lowing exa mple, the return arr ay is name d “ZZ” and the singl e security key to be checked i s the XUPR OG securit y key:
	9074	>K ZZ D OW NSKEY^XUSR B(.ZZ,“XUP ROG”) ZW Z Z
	9075	ZZ(0)=1
	9076
	9077	Example 2
	9078	In the fol lowing exa mple, the return sub scripted a rray is na med “ZZ” a nd the inp ut array o f security keys to b e checked is named “ LST”:
	9079	Figure 90: OWNSKEY^X USRB API—E xample
	9080	>K LST S L ST(1)=“XUP ROG”,LST(2 )=“XUMGR”, LST(3)=“AB C”
	9081	>K ZZ D OW NSKEY^XUSR B(.ZZ,.LST ) ZW ZZ
	9082	ZZ(1)=1
	9083	ZZ(2)=1
	9084	ZZ(3)=0
	9085
	9086
	9087
	9088	Server Opt ions: Deve loper Tool s
	9089	Tools for Processing Server Re quests
	9090	When a ser ver option runs, it can call c ustom prog rams to pe rform serv er-related tasks suc h as respo nding to t he sender of the ser ver reques t, or retr ieving the actual te xt of the server req uest messa ge. In thi s way, ser ver reques ts can act not only as trigger s, but als o as messa ge carrier s. The ser ver option can call custom pro grams via the follow ing fields :
	9091	ENTRY ACTI ON
	9092	HEADER
	9093	ROUTINE
	9094	EXIT ACTIO N
	9095	REF: For m ore inform ation on s erver opti ons, see S ection 11 in the Ker nel System s Manageme nt Guide.
	9096	REF: For m ore inform ation on t he develop er API for processin g server r equests, s ee the Mai lMan Devel oper’s Gui de.
	9097	Key Variab les When a Server Op tion is Ru nning
	9098	There are key variab les that a re set up when a ser ver option is runnin g. You can reference these key variables during an y routine run by the server op tion’s ENT RY ACTION, HEADER, R OUTINE, an d EXIT ACT ION fields . The key variables for server options a re set up as follows :
	9099	Table 30: Key variab le setup—S erver opti ons
	9100	Variable
	9101	Descriptio n
	9102	XQSOP
	9103	Server opt ion name.
	9104	XQMSG
	9105	Server req uest messa ge number.
	9106	XQSND
	9107	DUZ of the sender if the reque st is loca l; network address o f the send er if the request is not local
	9108	XQSUB
	9109	Subject he ading of t he server request me ssage.
	9110
	9111	Appending Text to a Server Req uest Bulle tin or Mai lman Reply
	9112	Server opt ions use b ulletins a nd MailMan messages to communi cate with the local system adm inistrator s when a s erver requ est is rec eived, or with the s ender of a server re quest, usu ally in th e event of an error. These two kinds of documents look very similar an d must con tain certa in key pie ces of dat a. It is a lso possib le, howeve r, for the sender or the local system ad ministrato rs to appe nd other i nformation to the bu lletin or MailMan me ssage by s etting tha t informat ion into t he array X QSTXT (one line per node). For example, if the fol lowing arr ay exists:
	9113	XQSTXT(0)= “Please ap pend these two lines of text”
	9114	XQSTXT(1)= “to the en d of the b ulletin XQ SERVER.”
	9115	The defaul t bulletin , XQSERVER , would th en look li ke:
	9116	Figure 91: XQSERVER— Default bu lletin
	9117	Subj: Serv er request notice
	9118	From: <Pos tmaster>
	9119	---------- ---------- ---------- ---------- ---------- ---------- ------
	9120
	9121	Dec. 21, 1 989 3:08 PM
	9122
	9123	A request for execut ion of a s erver opti on was rec eived.
	9124
	9125	Sender: <C hild,Your@ HOME. D O MAIN >
	9126	Option nam e: ZZUPDAT ECL
	9127	Subject: U PDATE CHRI STMAS LIST DATA BASE
	9128	Message #: 136771
	9129
	9130	Menu syste m Action: No error(s ) detected by the me nu system.
	9131
	9132	Please app end these two lines of text
	9133	to the end of the bu lletin XQS ERVER.
	9134
	9135	You can us e the same method to append te xt to Mail Man messag es.
	9136	Customizin g a Server Request B ulletin
	9137	Please not e that the first six data elem ents in a server req uest bulle tin are al ways:
	9138	The date a nd time th e request was receiv ed.
	9139	The sender .
	9140	The reques ted option ’s name.
	9141	The subjec t of the m essage of the server request.
	9142	The reques ting messa ge’s numbe r.
	9143	A brief st atement of the menu system’s a ction or a n error me ssage.
	9144	If you use a customi zed bullet in instead of XQSERV ER, these data eleme nts should always be printed f irst, foll owed by th e contents of XQSTXT .
	9145	The easies t way to c reate a cu stomized l ocal bulle tin is to use the VA FileMan c opy functi on to copy the defau lt bulleti n XQSERVER to a bull etin of an other name .
	9146	NOTE: XQSE RVER has a line of t ext in it that says: is th e server r equest bul letin XQSE RVERTo avo id confusi on, you sh ould edit this line using the Bulletin E dit option to reflec t the name of the ne w bulletin .
	9147
	9148
	9149	Signon/Sec urity: Dev eloper Too ls
	9150	Overview
	9151	Kernel’s S ignon/Secu rity modul e sets up a standard VistA pro gramming e nvironment as a foun dation for software applicatio ns. Once a signon se ssion has been creat ed, applic ations can assume th at system- wide varia bles exist for commo n referenc e. For exa mple, key variables defined vi a Signon/S ecurity in clude the user’s ins titution a nd agency (DUZ(2) an d DUZ(“AG” ), respect ively).
	9152	Direct Mod e Utilitie s
	9153	Several Si gnon/Secur ity direct mode util ities are available for develo pers to us e at the M prompt. T hey are no t APIs and cannot be used in s oftware ap plication routines. These util ities allo w develope rs to simu late ordin ary user s ignon and yet work f rom Progra mmer mode to test co de and dia gnose erro rs. These direct mod e utilitie s are desc ribed belo w.
	9154	^XUP: Prog rammer Sig non
	9155	The ^XUP r outine can be called as a quic k way to e nter Kerne l and set up a stand ard enviro nment:
	9156	>D ^XUP: P rogrammer Signon
	9157	It does th e followin g:
	9158	Sets up DT .
	9159	Calls ^%ZI S.
	9160	Prompts fo r Access c ode if DUZ is zero o r undefine d.
	9161	KILLs and rebuilds ^ XUTL(“XQ”, $J).
	9162	KILLs ^UTI LITY($J).
	9163	Calls ^XQ1 to prompt for an op tion if on e should b e run.
	9164
	9165	If a non-m enu-type o ption is s pecified, returning from the o ption disp lays the “ Select:” p rompt as t hough the option was a menu-ty pe. Althou gh this co nstruction may at fi rst appear misleadin g, restric ting optio n selectio n to menu- type only would be a functiona l limitati on to the call.
	9166	^XUS: User Signon: N o Error Tr apping
	9167	^XUS deter mines whet her access to the co mputer is allowed, a nd then se ts up the user with the proper environme nt:
	9168	>D ^XUS
	9169	This routi ne can be called to establish the signon environme nt. A reco mmended al ternative for develo pers is to call ^XUP , which es tablishes signon con ditions as well as c alling ^XQ 1 for an o ption name . Neither ^XUP nor ^ XUS sets t he Error T rap. Enter ing throug h ^ZU sets the Error Trap and then calls the ^XUS routine.
	9170	H^XUS: Pro grammer Ha lt
	9171	The follow ing is an obsolete u tility:
	9172	>D H^XUS
	9173	It simply transfers control to ^XUSCLEAN .
	9174	^XUSCLEAN: Programme r Halt
	9175	Developers are advis ed to call the ^XUSC LEAN routi ne when si gning off:
	9176	>D ^XUSCLE AN
	9177	It is the same code that Kerne l uses whe n a user s igns off o r restarts . It notes the signo ff time in the SIGN- ON LOG fil e (#3.081) and KILLs the $J no des in ^XU TL and ^UT ILITY. It then perfo rms a norm al halt.
	9178	^ZU: User Signon
	9179	The ZU rou tine sets the Error Trap and t hen calls ^XUS:
	9180	>D ^ZU
	9181	User signo ns should be tied to ^ZU.
	9182	XU USER SI GN-ON Opti on
	9183	Some softw are applic ations ask ed for the means to execute an action at user sign on, but no t through the alert system. Ke rnel provi des the XU USER SIGN -ON option that soft ware appli cations ca n attach t o and perf orm softwa re applica tion-speci fic tasks on user si gnon.
	9184	XU USER SI GN-ON: Pac kage-speci fic Signon Actions
	9185	Kernel 8.0 introduce d a method to suppor t software applicati on-specifi c signon a ctions. Ke rnel expor ts an exte nded-actio n option c alled XU U SER SIGN-O N. Package s that wan t Kernel t o execute a software applicati on-specifi c user sig non routin e can acco mplish thi s by attac hing their own optio n, of type action, t o Kernel’s XU USER S IGN-ON opt ion. Your action-typ e option s hould call your soft ware appli cation-spe cific user signon ro utine.
	9186	To attach your optio n to the X U USER SIG N-ON optio n, make yo ur option an item of the XU US ER SIGN-ON protocol; then, exp ort your o ption with a KIDS ac tion of SE ND, and ex port the X U USER SIG N-ON optio n with a K IDS action of USE AS LINK FOR MENU ITEMS .
	9187	During sig non, Kerne l executes the XU US ER SIGN-ON option, w hich in tu rn execute s any opti ons that s oftware ap plications have atta ched to XU USER SIGN -ON. No da tabase Int egration C ontrol Reg istrations are requi red to att ach to the XU USER S IGN-ON opt ion.
	9188	If you nee d to perfo rm any out put during your acti on, you sh ould use t he SET^XUS 1A functio n to perfo rm the out put. Outpu t is not i mmediate, but occurs once all software a pplication -specific signon act ions have completed. Also, you should no t perform any tasks requiring interactio n in an ac tion attac hed to the XU USER S IGN-ON opt ion.
	9189	The DUZ va riable is defined at the time the signon actions a re execute d; DUZ is set as it normally i s to the p erson’s In ternal Ent ry Number (IEN) in t he NEW PER SON file ( #200).
	9190	Take care to make co de efficie nt, since executed b y every si gnon. A fe w examples of tasks you might want to ac complish d uring sign on are:
	9191	Alert the user to a software a pplication status.
	9192	Issue a re minder.
	9193	Notify the software applicatio n of the s ignon of a software applicatio n user.
	9194	Example
	9195	The follow ing option , when att ached to t he XU USER SIGN-ON p rotocol, o utputs one line duri ng signon:
	9196	Figure 92: XU USER S IGN-ON—Sam ple ZZTALK Protocol
	9197	NAME: ZZTA LK PROTOCO L MENU TEXT: TALKING P ROTOCOL
	9198	TYPE: ac tion E ACTION P RESENT: YE S
	9199	DESCRIPTI ON: USE TO TEST EX TENDED ACT ION PROTOC OLS
	9200	ENTRY AC TION: D SE T^XUS1A(“! This line is from th e ZZTALK o ption.”)
	9201	UPPERCAS E MENU TEX T: TALKING PROTOCOL
	9202
	9203	XU USER ST ART-UP Opt ion
	9204	VistA soft ware devel opers aske d for the means to e xecute an action at VistA user signon, b ut not thr ough the a lert syste m. Added w ith Kernel patch XU* 8.0*593, t he XU USER START-UP option is a protocol option us ed exclusi vely durin g a VistA user signo n event. I tems attac hed to thi s option a re “TYPE: action” op tions in t he OPTION file (#19) , which ca n be used for softwa re-specifi c actions that promp t users fo r input up on VistA s ignon befo re their P rimary Men u Option i s displaye d. Unlike the XU USE R SIGN-ON option, it can provi de interac tive promp ting to us ers. It is not used for GUI si gnon. It i s called f rom the XQ 12 routine .
	9205	XU USER ST ART-UP: Ap plication- specific S ignon Acti ons
	9206	Kernel 8.0 introduce d a method to suppor t applicat ion-specif ic VistA ( non-GUI) s ignon acti ons. Kerne l patch XU 8.0593 e xports the XU USER S TART-UP ex tended-act ion option . VistA ap plications that want Kernel to execute a n applicat ion-specif ic user si gnon routi ne can do this by at taching th eir own op tion, of T YPE: actio n, to Kern el’s XU US ER START-U P option. The action -type opti on should call the a pplication -specific user signo n routine.
	9207	To attach your optio n to the X U USER STA RT-UP opti on, perfor m the foll owing proc edure:
	9208	Make your option an item of th e XU USER START-UP p rotocol.
	9209	Export you r option w ith a KIDS action of SEND.
	9210	Export the XU USER S TART-UP op tion with a KIDS act ion of USE AS LINK F OR MENU IT EMS.
	9211	During sig non, Kerne l executes the XU US ER START-U P option b efore the user’s Pri mary Menu Option is displayed, which in turn execu tes any op tions that applicati ons have a ttached to XU USER S TART-UP. N o database Integrati on Control Registrat ions are r equired to attach to the XU US ER START-U P option.
	9212	Since this option is only used for VistA signon se ssions and not GUI s ignon, tas ks requiri ng interac tion are p ermitted. If you wan t a task t o prevent a user fro m signing on, then t he task sh ould set t he variabl e XUSQUIT= 1.
	9213	The DUZ va riable is defined at the time the signon actions a re execute d; DUZ is set as it normally i s to the p erson’s In ternal Ent ry Number (IEN) in t he NEW PER SON file ( #200).
	9214	Take care to make co de efficie nt, since it is exec uted at ev ery VistA signon. Th e followin g are exam ples of ta sks you mi ght want t o accompli sh during a VistA si gnon:
	9215	Prompt the user to u pdate thei r phone nu mber in th e NEW PERS ON file (# 200).
	9216	Block a us er’s acces s unless t hey electr onically s ign a secu rity agree ment.
	9217	Example:
	9218	The follow ing option , when att ached to t he XU USER SIGN-ON p rotocol, o utputs one line duri ng signon:
	9219	Figure 93: XU USER S TART-UP op tion—Sampl e signon a ction-type option
	9220	NAME: ZZXU 593 SAMPLE OPTION
	9221	TYPE: acti on E ACTIO N PRESENT: YES
	9222	DESCRIPTIO N: PROMPT USER TO ED IT SIGNATU RE BLOCK
	9223	ENTRY ACTI ON: D SAMP LE^XQ12
	9224	UPPERCASE MENU TEXT: SAMPLE OP TION
	9225
	9226	XU USER TE RMINATE Op tion
	9227	Kernel 8.0 introduce d a method to suppor t software applicati on-specifi c user ter mination a ctions. Ke rnel 8.0 e xports an extended-a ction opti on called XU USER TE RMINATE. P ackages th at want Ke rnel to ex ecute a so ftware app lication-s pecific us er termina tion actio n can acco mplish thi s by attac hing their own optio n, of type action, t o Kernel’s XU USER T ERMINATE e xtended ac tion.
	9228	Discontinu ation of U SER TERMIN ATE ROUTIN E
	9229	Kernel 7.1 introduce d a method for softw are applic ations to have Kerne l execute a software applicati on-specifi c routine when Kerne l terminat ed a user. The metho d was for the softwa re applica tion to ha ve a routi ne tag and name in f ields 200. 1 (USER TE RMINATE TA G) and 200 .2 (USER T ERMINATE R OUTINE) of the softw are applic ation’s PA CKAGE file (#9.4) en try. When Kernel 7.1 terminate d a user, it execute d the TAG^ ROUTINE AP I stored i n these fi elds, if a ny.
	9230	Kernel 8.0 continues to execut e the API, if any, s tored in a software applicatio n’s PACKAG E file (#9 .4) entry. However, Kernel 8.0 is the la st version to suppor t that met hod of sof tware appl ication-sp ecific use r terminat ion routin es.
	9231	Creating a Package-s pecific Us er Termina tion Actio n
	9232	Beginning with Kerne l 8.0, you should cr eate an ac tion-type option tha t calls yo ur softwar e applicat ion-specif ic user te rmination routine. T o attach i t to the X U USER TER MINATE opt ion, do th e followin g:
	9233	Export you r option w ith a KIDS action of SEND.
	9234	Export the XU USER T ERMINATE o ption with a KIDS ac tion of US E AS LINK FOR MENU I TEMS.
	9235	Kernel def ines the X UIFN varia ble at the time your action ex ecutes; it is define d as the I nternal En try Number (IEN) in the NEW PE RSON file (#200) of the user b eing termi nated.
	9236	When termi nating a u ser, Kerne l executes the XU US ER TERMINA TE option, which in turn execu tes any op tions atta ched to XU USER TERM INATE. No database I ntegration Control R egistratio ns are req uired to a ttach to t he XU USER TERMINATE option.
	9237	A few exam ples of us er clean u p you migh t want to accomplish when Kern el termina tes users are as fol lows:
	9238	Removal of HINQ acce ss.
	9239	Removal of Control P oint acces s.
	9240	Removal fr om health care teams .
	9241	Applicatio n Programm ing Interf ace (API)
	9242	Several AP Is are ava ilable for developer s to work with signo n/security . These AP Is are des cribed bel ow.
	9243	$$GET^XUPA RAM(): Get Parameter s
	9244	Reference Type:Suppo rted
	9245	Category:S ignon/Secu rity
	9246	ICR #:2542
	9247	Descriptio n:This ext rinsic fun ction gets simple pa rameters f rom the KE RNEL PARAM ETERS file (#8989.2) that the site can e dit.
	9248	Format:$$G ET^XUPARAM (parameter _name[,sty le])
	9249	Input Para meters:par ameter_nam e:(require d) This is the names paced name of the pa rameter to look up i n the KERN EL PARAMET ERS file ( #8989.2) a nd return the REPLAC EMENT valu e or DEFAU LT.
	9250	style:(opt ional) Thi s input pa rameter co ntrols the return va lue if the REPLACEME NT value o r DEFAULT is empty.
	9251	Output:ret urns:Retur ns the REP LACEMENT v alue or DE FAULT.
	9252
	9253	$$KSP^XUPA RAM(): Ret urn Kernel Site Para meter
	9254	Reference Type:Suppo rted
	9255	Category:S ignon/Secu rity
	9256	ICR #:2541
	9257	Descriptio n:This ext rinsic fun ction retr ieves a Ke rnel site parameter. The follo wing param eters are currently supported:
	9258	INST
	9259	SPOOL DOC
	9260	SPOOL LIFE
	9261	SPOOL LINE
	9262	WHERE
	9263	Format:$$K SP^XUPARAM (param)
	9264	Input Para meters:par am:(requir ed) Site p arameter t o retrieve . Currentl y, the fol lowing val ues for pa ram are su pported:
	9265	INST—Inter nal Entry Number (IE N) of the site’s ins titution, in the sit e’s INSTIT UTION file (#4).
	9266	SPOOL DOC— MAX SPOOL DOCUMENTS PER USER ( internal v alue) from the site’ s KERNEL S YSTEM PARA METERS fil e (#8989.3 ).
	9267	SPOOL LIFE —MAX SPOOL DOCUMENT LIFE-SPAN (internal value) fro m the site ’s KERNEL SYSTEM PAR AMETERS fi le (#8989. 3).
	9268	SPOOL LINE —MAX SPOOL LINES PER USER (int ernal valu e) from si te’s KERNE L SYSTEM P ARAMETERS file (#898 9.3).
	9269	WHERE—Site ’s domain name (FREE TEXT valu e), from t he site’s DOMAIN fil e (#4.2).
	9270	Output:ret urns:Retur ns the req uested sit e paramete r value.
	9271
	9272	Examples
	9273	Example 1
	9274	>S A6ASITE =$$KSP^XUP ARAM(“WHER E”)
	9275
	9276	Example 2
	9277	>S A6ASPLL F=$$KSP^XU PARAM(“SPO OL LIFE”)
	9278
	9279	$$LKUP^XUP ARAM(): Lo ok Up Para meters
	9280	Reference Type:Suppo rted
	9281	Category:S ignon/Secu rity
	9282	ICR #:2542
	9283	Descriptio n:This ext rinsic fun ction look s up simpl e paramete rs from th e KERNEL P ARAMETERS file (#898 9.2) that the site c an edit.
	9284	Format:$$L KUP^XUPARA M(paramete r_name[,st yle])
	9285	Input Para meters:par ameter_nam e:(require d) This is the names paced name of the pa rameter to look up i n the KERN EL PARAMET ERS file ( #8989.2) a nd return the REPLAC EMENT valu e or DEFAU LT.
	9286	style:(opt ional) Thi s input pa rameter co ntrols the return va lue if the REPLACEME NT value o r DEFAULT is empty.
	9287	Output:ret urns:Retur ns the REP LACEMENT v alue or DE FAULT.
	9288
	9289	SET^XUPARA M(): Set P arameters
	9290	Reference Type:Suppo rted
	9291	Category:S ignon/Secu rity
	9292	ICR #:2542
	9293	Descriptio n:This API sets simp le paramet ers in the KERNEL PA RAMETERS f ile (#8989 .2).
	9294	Format:SET ^XUPARAM(p arameter_n ame[,style ])
	9295	Input Para meters:par ameter_nam e:(require d) This is the names paced name of the pa rameter to set in th e KERNEL P ARAMETERS file (#898 9.2).
	9296	style:(opt ional) Thi s input pa rameter co ntrols the return va lue if the REPLACEME NT value o r DEFAULT is empty.
	9297	Output:non e.
	9298
	9299	$$PROD^XUP ROD(): Pro duction Vs . Test Acc ount
	9300	Reference Type:Suppo rted
	9301	Category:S ignon/Secu rity
	9302	ICR #:4440
	9303	Descriptio n:This API was relea sed with K ernel patc h XU8.02 84. It is called by applicatio ns to chec k and see if the app lication i s running in a Produ ction or a Test acco unt.
	9304	The Ask if Productio n Account option [XU SID ASK] on the Ker nel Manage ment Menu [XUKERNEL] , asks if the curren t account is the Pro duction ac count. It returns th e followin g values:
	9305	True (1 or non-zero) —If the an swer is YE S, the acc ount is th e Producti on account , so the c urrent sys tem ID (SI D) is set as the Pro duction SI D.
	9306	False (zer o)—If the answer is NO, the ac count is n ot the Pro duction ac count, so a fake val ue is stor ed.
	9307	The Startu p PROD che ck option [XU SID ST ARTUP] can be schedu led for st artup so t hat when T askMan sta rts the SI D is check ed. The fi rst check each day g ets the cu rrent SID and compar es it with the store d SID to s ee if they match.
	9308	Format:$$P ROD^XUPROD ([force])
	9309	Input Para meters:for ce:(option al) The pa rameter va lue of 1 a llows an a pplication to force a full tes t.
	9310	Output:ret urns:Retur ns a Boole an value:
	9311	True (1 or non-zero) —Productio n account, current S ID is set as the Pro duction SI D.
	9312	False (zer o)—Test ac count.
	9313
	9314	H^XUS: Pro grammer Ha lt
	9315	Reference Type:Suppo rted
	9316	Category:S ignon/Secu rity
	9317	ICR #:1004 4
	9318	Descriptio n:This API is the Pr ogrammer H alt.
	9319	Format:H^X US
	9320	Input Para meters:non e.
	9321	Output:non e.
	9322
	9323	SET^XUS1A( ): Output Message Du ring Signo n
	9324	Reference Type:Suppo rted
	9325	Category:S ignon/Secu rity
	9326	ICR #:3057
	9327	Descriptio n:This API performs any output during a software a pplication -specific action exe cuted at s ignon. Thi s function should on ly be used by action -type opti ons attach ed to and executed b y Kernel’s XU USER S IGN-ON ext ended acti on.
	9328	Display of the strin g is not i mmediate; instead, e very call to SET^XUS 1A appends a node to an array containing the post signon tex t. When al l software applicati on-specifi c signon a ctions hav e complete d, the sig non proces s then dis plays the post signo n text arr ay, which also conta ins any st rings regi stered wit h the SET^ XUS1A func tion, appe nded at th e end.
	9329	Format:SET ^XUS1A(str ing)
	9330	Input Para meters:str ing:(requi red) Strin g to outpu t. First c haracter i s stripped from stri ng; if the first cha racter is an exclama tion point , a line f eed is iss ued before the strin g is displ ayed; othe rwise, no line feed is issued.
	9331	Output:non e.
	9332
	9333	Details
	9334	As of Kern el 8.0, so ftware app lications can attach an action -type opti on to a Ke rnel exten ded action -type opti on called XU USER SI GN-ON. Thi s option, and all at tached act ion-types, are execu ted during every sig non.
	9335	REF: For m ore inform ation on s oftware ap plication- specific a ction exec uted at si gnon, see the “XU US ER SIGN-ON : Package- specific S ignon Acti ons” secti on.
	9336	AVHLPTXT^X US2: Get H elp Text
	9337	Reference Type:Contr olled Subs cription
	9338	Category:S ignon/Secu rity
	9339	ICR #:4057
	9340	Descriptio n:This API retrieves help text to displa y to the u ser when t hey change their Ver ify code.
	9341	Format:AVH LPTXT^XUS2
	9342	Input Para meters:non e.
	9343	Output:ret urns:Retur ns the hel p text for a user to use when entering a new Verif y code.
	9344
	9345	$$CREATE^X USAP: Crea te Applica tion Proxy User
	9346	Reference Type:Contr olled Subs cription
	9347	Category:S ignon/Secu rity
	9348	ICR #:4677
	9349	Descriptio n:Released with Kern el patch X U8.0361, this extr insic func tion is a non-intera ctive API to create an Applica tion Proxy User to s upport J2E E middle-t ier applic ations. Th e Applicat ion Proxy User repre sents an a pplication and not a n end-user .
	9350	CAUTION: I f the user running t his extrin sic functi on does no t hold the XUMGR sec urity key, it return s an error upon the filing of the Applic ation Prox y as the U ser Class.
	9351	Overview
	9352	The Applic ation Prox y User is a special category o f user acc ount that is created in the NE W PERSON f ile (#200) and can r un interna l tasks or execute a uthorized Remote Pro cedure Cal ls (RPCs). The Appli cation Pro xy represe nts an app lication a nd not an end-user. The Applic ation Prox y user acc ount must adhere to the follow ing criter ia:
	9353	The name a dded to th e NEW PERS ON file (# 200) must be unique and must b e namespac ed in acco rdance wit h M Progra mming Stan dards and Convention s (SAC) Se ction 2.6, “Name Req uirements. ”
	9354	It must ha ve a user class of “ Applicatio n Proxy,” as defined in the US ER CLASS f ile (#201) and point ed to by t he USER CL ASS field (#9.5) in the NEW PE RSON file (#200).
	9355	It must no t have an Access or Verify cod e assigned to it.
	9356	It must no t have a P rimary men u assigned to it.
	9357	It must ha ve one or more Secon dary menu options as signed to it. The Se condary me nu option must be ow ned by the applicati on that th e Applicat ion Proxy represents , or the a pplication must have an Integr ation Cont rol Regist ration (IC R) with th e option o wner. The Secondary menu optio n contains a list of RPCs that the Appli cation Pro xy is auth orized to call, as d escribed i n the “RPC Security” section i n the RPC Broker Use r Guide.
	9358	The RPCs t hat the me nu options reference must have the APP P ROXY ALLOW ED field ( #.11) in t he REMOTE PROCEDURE file (#899 4) set to YES. The R PCs must b e owned by the appli cation tha t the Appl ication Pr oxy repres ents, or t he applica tion must have an IC R with the RPC owner .
	9359	The use of an Applic ation Prox y must be restricted to access ing non-pr otected da ta. Federa l laws spe cify when an actual end-user m ust be rep resented w hen access ing Person ally Ident ifiable In formation (PII) and Protected Health Inf ormation ( PHI). Info rmation re garding us er authent ication, i dentity, a uditing, a nd authori zation can be found in:
	9360	VA Informa tion Secur ity Handbo ok 6500 Ap pendix F
	9361	National I nstitute o f Standard s and Tech nology (NI ST) e-Auth entication Guideline s (800-63- 2)
	9362	Health Ins urance Por tability a nd Account ability Ac t of 1996 (HIPAA) fe deral law 45 CFR § 1 60 & § 164
	9363	Applicatio n Proxy Pr ivacy and Auditing
	9364	Many VistA data inte ractions b y human en d-users mu st be repr esented wi th accurat e and unam biguous us er identit y informat ion, so th at VistA a udit mecha nisms func tion as in tended. Ap plication Proxy user accounts do not ide ntify the user and s hould be a voided, es pecially w here the i nteraction is with P HI/PII dat a (regulat ed by fede ral law). The use of Applicati on Proxy u ser accoun ts should be limited to backgr ound proce sses and m achine-to- machine in teractions .
	9365	Applicatio n Proxy Pe rmission
	9366	The $$CREA TE^XUSAP i s used to create an Applicatio n Proxy. P ermission to use thi s API shou ld be done early in the develo pment proc ess, as us e of Appli cation Pro xy user ac counts are reviewed by VA mana gement due to securi ty concern s.
	9367	Format:$$C REATE^XUSA P(proxyuse rname[,fil emanaccess code][,opt ions])
	9368	Input Para meters:pro xyusername :(required ) This is the name o f the Appl ication Pr oxy User. This name must be un ique and s hould be n amespaced.
	9369	filemanacc esscode:(o ptional) T his is the VA FileMa n Access c ode. It ca nnot be an at-sign ( “@”).
	9370	REF: For m ore inform ation, see the VA Fi leMan Adva nced User Manual.
	9371	options:(o ptional) T his is the name of a single op tion name (e.g., XUS TEST PROX Y LOGON) o r an array of option s, such as XUOPT(“XM USER”)=1. Applicatio ns can onl y access t he Remote Procedure Calls (RPC s) contain ed in the options pr ovided in this input parameter . RPCs are tied to “ B”-type op tions.
	9372	Output:ret urns:Retur ns:
	9373	IEN of ent ry created in NEW PE RSON file (#200)—Suc cessful; w rites new Applicatio n Proxy Us er to the NEW PERSON file (#20 0).
	9374	“0^Name In Use”—Unsu ccessful; Applicatio n Proxy Us er of that name alre ady exists in the NE W PERSON f ile (#200) .
	9375	-1—Unsucce ssful; cou ld not cre ate Applic ation Prox y User OR error in c all to UPD ATE^DIE.
	9376	NOTE: For more infor mation on the UPDATE ^DIE-relat ed error, users shou ld check ^ TMP(“DIERR ”,$J).
	9377
	9378	Examples
	9379	Applicatio n Proxy Ex ample (Goo d)
	9380	The follow ing exampl e shows a successful creation of an Appl ication Pr oxy User:
	9381	>IF $$CREA TE^XUSAP(" VPR,APPLIC ATION PROX Y","","VPR APPLICATI ON PROXY") >0 W !,"Pr oxy Create d"
	9382
	9383	Proxy Crea ted
	9384
	9385	Figure 94 is an exam ple of an Applicatio n Proxy us er account that is p rovisioned correctly :
	9386	Figure 94: Applicati on Proxy E xample (Go od)
	9387	NAME: VPR, APPLICATIO N PROXY DATE ENTER ED: SEP 01 , 2011
	9388	CREATOR: PROGRAMME R,ONE
	9389	SECONDARY MENU OPTIO NS: VPR AP PLICATION PROXY
	9390	TIMESTAM P: 62335,6 2903
	9391	User Class : APPLICAT ION PROXY ISPRIMARY: Yes
	9392
	9393	The Proxy User List option [XU SAP PROXY LIST] list s the curr ent Applic ation Prox y user acc ounts, as shown in F igure 95:
	9394	Figure 95: Applicati on Proxy E xample (Go od)—Displa yed using Proxy User List opti on
	9395	PROXY USER LIST JAN 28,2016 09:44 P AGE 1
	9396	NAME Use r Class IsP rimary Ac tive
	9397	---------- ---------- ---------- ---------- ---------- ---------- ---------- ----------
	9398
	9399	XOBVTESTER ,APPLICATI ON PROXY APP LICATION P ROXY Yes
	9400	ANRVAPPLIC ATION,PROX Y USER APP LICATION P ROXY Yes
	9401	VPFS,APPLI CATION PRO XY APP LICATION P ROXY Yes
	9402	RADIOLOGY, OUTSIDE SE RVICE APP LICATION P ROXY Yes
	9403	LRLAB,HL APP LICATION P ROXY Yes
	9404	LRLAB,POC APP LICATION P ROXY Yes
	9405	TASKMAN,PR OXY USER APP LICATION P ROXY Yes
	9406	CLINICAL,D EVICE PROX Y SERVICE APP LICATION P ROXY Yes
	9407	NHIN,APPLI CATION PRO XY APP LICATION P ROXY Yes
	9408	EDPTRACKIN G,PROXY APP LICATION P ROXY Yes
	9409	KAAJEE,PRO XY APP LICATION P ROXY Yes
	9410	VPR,APPLIC ATION PROX Y APP LICATION P ROXY Yes
	9411	AUTHORIZER ,IB REG APP LICATION P ROXY Yes
	9412	HOWDY,BOT APP LICATION P ROXY Yes
	9413	LRLAB,TASK MAN APP LICATION P ROXY Yes
	9414	VIABAPPLIC ATIONPROXY ,VIAB APP LICATION P ROXY Yes
	9415
	9416	CAUTION: S ome of the listed Ap plication Proxy user accounts do not fol low the ru les for na mespacing. There are other ser ious infra ctions in current ap plications using App lication P roxy user accounts, which puts the VA in the posit ion of vio lating fed eral priva cy laws by accessing PHI/PII i nformation . VA Handb ook 6500 A ppendix F lists VA S ystem Secu rity Contr ols that a re applica ble to App lication P roxy user accounts a s well as human end- users. An Applicatio n Proxy sh ould never be used t o circumve nt VA Syst em Securit y Controls .
	9417	Applicatio n Proxy Ex ample (Bad )
	9418	Figure 96 is an exam ple of an Applicatio n Proxy us er account that is n ot provisi oned corre ctly:
	9419	Figure 96: Applicati on Proxy E xample (Ba d) (1 of 2 )
	9420	NAME: TASK MAN,PROXY USER FILE MANAG ER ACCESS CODE: #
	9421	DATE ENT ERED: JUN 9,2009 CREATOR: L ABTECH,FOR TYEIGHT
	9422	NAME COM PONENTS: 2 00
	9423	SIGNATUR E BLOCK PR INTED NAME : PROXY US ER TASKMAN
	9424	TIMESTAM P: 62362,5 3550
	9425	User Class : APPLICAT ION PROXY ISPRIMARY: Yes
	9426
	9427	If provisi oned corre ctly, the name “TASK MAN, PROXY USER” wou ld be iden tified by the Kernel (XU) name space, suc h as “XUTA SKMAN,PROX Y USER”. T his partic ular Appli cation Pro xy does no t require access to any menu o ptions or RPCs, so i t does not contain a SECONDARY MENU OPTI ON.
	9428	Figure 97 is another example o f an Appli cation Pro xy user ac count that is not pr ovisioned correctly:
	9429	Figure 97: Applicati on Proxy E xample (Ba d) (2 of 2 )
	9430	NAME: CLIN ICAL,DEVIC E PROXY SE RVICE DATE ENTER ED: JUN 30 ,2010
	9431	CREATOR: PROGRAMME R,ONE
	9432	SECONDARY MENU OPTIO NS: MD GUI MANAGER
	9433	SECONDARY MENU OPTIO NS: MD GUI USER
	9434	TIMESTAM P: 61907,7 1682
	9435	User Class : APPLICAT ION PROXY ISPRIMARY: Yes
	9436
	9437	In this ex ample, the SECONDARY MENU OPTI ONs are in the Clini cal Proced ures (MD) namespace, so that i f provisio ned correc tly, “CLIN ICAL,DEVIC E PROXY SE RVICE” wou ld be more appropria tely named “MDCLINIC AL,DEVICE PROXY SERV ICE”.
	9438	KILL^XUSCL EAN: Clear all but K ernel Vari ables
	9439	Reference Type:Suppo rted
	9440	Category:S ignon/Secu rity
	9441	ICR #:1005 2
	9442	Descriptio n:This API clears th e partitio n of all b ut key var iables ess ential to Kernel. Ap plication developers are allow ed to use this call to clean u p applicat ion variab les and le ave the lo cal symbol table unc hanged whe n returnin g from an option or as otherwi se require d by SAC S tandards.
	9443	In the pas t, options that have called KI LL^XUSCLEA N have occ asionally created pr oblems for other opt ions that had define d software -wide vari ables. For example, a user mig ht enter t he top-lev el menu fo r a softwa re applica tion, whic h could ha ve an entr y action t hat retrie ved site p arameters into a loc al variabl e that is supposed t o remain d efined whi le in any menu of th at softwar e applicat ion, betwe en options . But if t he user co uld then r each a sec ondary men u option t hat happen ed to call KILL^XUSC LEAN, a si de effect would be t he KILLing off the p reviously defined so ftware-wid e variable .
	9444	KILL^XUSCL EAN now pr ovides a w ay for sit es and dev elopers to work arou nd this pr oblem. For any menu- type optio n, the PRO TECTED VAR IABLES fie ld in the OPTION fil e (#19) al lows you t o enter a comma-deli mited list of variab les to pro tect from being KILL ed by KILL ^XUSCLEAN. Once a us er enters a menu sub tree desce ndent from the prote cted menu, the varia bles are p rotected u ntil the m enu subtre e is exite d.
	9445	So, for ex ample, to protect a software-w ide variab le for an entire sof tware appl ication, y ou can ent er that va riable in the PROTEC TED VARIAB LES field for the to p-level me nu in the software a pplication . As long as a user does not e xit the to p-level me nu of the software a pplication ’s menu tr ee, the so ftware-wid e variable is protec ted from a ll calls t o KILL^XUS CLEAN. “Up -arrow Jum ps” into a menu tree also work fine, as long as th e menu tha t has been protected is in the menu path made by t he jump.
	9446	Format:KIL L^XUSCLEAN
	9447	Input Para meters:non e.
	9448	Output:non e.
	9449
	9450	$$ADD^XUSE RNEW(): Ad d New User s
	9451	Reference Type:Suppo rted
	9452	Category:S ignon/Secu rity
	9453	ICR #:1005 3
	9454	Descriptio n:This ext rinsic fun ction adds new entri es to the NEW PERSON file (#20 0). It was modified with Kerne l patch XU 8.0134. After prom pting for the user’s name, it parses the input int o its comp onent part s, and the n prompts for each n ame compon ent separa tely, pres enting the parsed in put as def aults. It then promp ts for the default i dentifiers for the N EW PERSON file (#200 ) entry in the follo wing order :
	9455	INITIAL (# 1)
	9456	SSN (#9)
	9457	SEX (#4)
	9458	If the use r of this function h as the XUS PF200 secu rity key, entry of t he SSN is not requir ed. The de fault iden tifiers ca n be local ly modifie d by modif ying the N EW PERSON IDENTIFIER S field in the KERNE L SYSTEM P ARAMETERS file (#898 9.3).
	9459	To prompt for additi onal field s during t his call, you pass a DR string containin g the fiel ds for whi ch you wis h to promp t as a par ameter to this funct ion. If th e person a dding the entry ente rs a caret (“^”) to exit out b efore fill ing in all the ident ifiers and requested fields, t he entry i s removed from the N EW PERSON file (#200 ), and -1 is returne d.
	9460	Format:$$A DD^XUSERNE W([dr_stri ng][,keys] )
	9461	Input Para meters:dr_ string:(op tional) Ad ditional f ields to a sk when ad ding the n ew user, i n the form at for a D R string a s used in a standard DIC call.
	9462	REF: For i nformation about DIC , see the VA FileMan documenta tion.
	9463	keys:(opti onal) A co mma-delimi ted string of keys t o assign t o the newl y created user.
	9464	Output:ret urns:Retur ns a value similar i n format t o the valu e of “Y” r eturned fr om a stand ard DIC ca ll:
	9465	-1—User ne ither exis ted nor co uld be add ed.
	9466	N^S—User a lready exi sts in the file; N i s the inte rnal numbe r of the e ntry in th e file, an d S is the value of the .01 fi eld for th at entry.
	9467	N^S^1—N an d S are de fined as a bove, and the 1 indi cates the user has j ust been a dded to th e file.
	9468	REF: For i nformation about DIC , see the VA FileMan documenta tion.
	9469
	9470	Examples
	9471	Example 1
	9472	To add a n ew user, a sking defa ult fields for new e ntry:
	9473	Figure 98: $$ADD^XUS ERNEW API— Example of adding a new user
	9474	>S X=$$ADD ^XUSERNEW
	9475
	9476	Enter NEW PERSON’s n ame (Famil y,Given Mi ddle Suffi x): XUUSER ,TWO E
	9477	Are you a dding ‘XUU SER,TWO E’ as a new NEW PERSON (the 1602 ND)? No// Y <Enter> (Yes)
	9478	Checking S OUNDEX for matches.
	9479	No matches found.
	9480	Name compo nents.
	9481	FAMILY (LA ST) NAME: XUUSER// < Enter>
	9482	GIVEN (FIR ST) NAME: TWO// <Ent er>
	9483	MIDDLE NAM E: E// <En ter>
	9484	SUFFIX: <E nter>
	9485	Now for th e Identifi ers.
	9486	INITIAL: T EX
	9487	SSN: 00022 2222
	9488	SEX: M <En ter> MALE
	9489	>W X
	9490	1000118^XU USER,TWO E ^1
	9491	>
	9492
	9493	Example 2
	9494	To add a n ew user, s pecifying a key to a dd:
	9495	>S X=$$ADD ^XUSERNEW( “”,“PROVID ER”)
	9496
	9497	Example 3
	9498	To add a n ew user, s pecifying additional fields to ask, plus two keys to add:
	9499	>S X=$$ADD ^XUSERNEW( “5;13;53”, “PSMGR,PSN ARC”)
	9500
	9501	$$CHECKAV^ XUSRB(): C heck Acces s/Verify C odes
	9502	Reference Type:Contr olled Subs cription
	9503	Category:S ignon/Secu rity
	9504	ICR #:2882
	9505	Descriptio n:This ext rinsic fun ction chec ks an Acce ss/Verify code pair (delimited by a semi -colon) an d returns whether or not it is a valid p air.
	9506	Format:$$C HECKAV^XUS RB(access_ verify)
	9507	Input Para meters:acc ess_verify :(required ) This is a string c ontaining the Access and Verif y code pai r delimite d by a sem i-colon (i .e., Acces s code;Ver ify code).
	9508	Output:ret urns:Retur ns:
	9509	Internal E ntry Numbe r (IEN)—Co des are OK .
	9510	Zero (0)—C odes are n ot OK.
	9511
	9512	Example
	9513	>S X=$CHEC KAV^XUSRB( <string>)
	9514
	9515	String = A ccess code ;Verify co de
	9516	CVC^XUSRB: VistALink —Change Us er’s Verif y Code
	9517	Reference Type:Contr olled Subs cription
	9518	Category:S ignon/Secu rity
	9519	ICR #:4054
	9520	Descriptio n:This API changes a VistALink user’s Ve rify code.
	9521	Format:CVC ^XUSRB
	9522	Input Para meters:non e.
	9523	Output Var iables:DUZ :If DUZ is defined, you can co nsider the “change v erify code ” operatio n to have been succe ssful.
	9524
	9525	$$INHIBIT^ XUSRB: Che ck if Logo ns Inhibit ed
	9526	Reference Type:Suppo rted
	9527	Category:S ignon/Secu rity
	9528	ICR #:3277
	9529	Descriptio n:This ext rinsic fun ction chec ks if logo ns have be en inhibit ed.
	9530	Format:$$I NHIBIT^XUS RB
	9531	Input Para meters:non e.
	9532	Output:non e.
	9533
	9534	INTRO^XUSR B: VistALi nk—Get Int roductory Text
	9535	Reference Type:Contr olled Subs cription
	9536	Category:S ignon/Secu rity
	9537	ICR #:4054
	9538	Descriptio n:This API retrieves the intro ductory te xt from M to display in VistAL ink.
	9539	Format:INT RO^XUSRB
	9540	Input Para meters:non e.
	9541	Output:ret urns:Retur ns each li ne in the introducto ry text as a value s tored at t he first s ubscript l evel node of the pas s-by-refer ence first parameter to the me thod call. For examp le:
	9542	RETURN(0)= line 1 RET URN(1)=lin e 2 etc.
	9543
	9544	LOGOUT^XUS RB: VistAL ink—Log Ou t User fro m M
	9545	Reference Type:Contr olled Subs cription
	9546	Category:S ignon/Secu rity
	9547	ICR #:4054
	9548	Descriptio n:This API logs out a VistALin k user fro m M.
	9549	Format:LOG OUT^XUSRB
	9550	Input Para meters:non e.
	9551	Output:non e.
	9552
	9553	SETUP^XUSR B(): Vist ALink—Set Up User’s Partition in M
	9554	Reference Type:Contr olled Subs cription
	9555	Category:S ignon/Secu rity
	9556	ICR #:4054
	9557	Descriptio n:This API sets up a VistALink user’s pa rtition in M prior t o signon.
	9558	Format:SET UP^XUSRB(r et)
	9559	Make sure to perform the follo wing steps before ca lling this API:
	9560	NEW all no n-namespac ed variabl es.
	9561	Set all in put variab les.
	9562	Call the A PI.
	9563	Input Para meters:ret :(required ) Name of the subscr ipted retu rn array. In every A PI that is used as a n RPC, the first par ameter is the return array.
	9564	Input Vari ables:XWBT IP:(requir ed) The In ternet Pro tocol (IP) address o f the clie nt worksta tion.
	9565	XWBCLMAN:( optional) The client workstati on name.
	9566	XWBVER:(op tional) Th is is the version of the RPC B roker soft ware on th e client w orkstation .
	9567	Output:ret ():Returns a subscri pted outpu t array:
	9568	RET(0)—Ser ver option nameRET(1 )—VolumeRE T(2)—UCIRE T(3)—Devic eRET(4)—# AttemptsRE T(5)—Skip signon-scr eenRET(6)— Domain nam e
	9569
	9570	VALIDAV^XU SRB(): Vis tALink—Val idate User Credentia ls
	9571	Reference Type:Contr olled Subs cription
	9572	Category:S ignon/Secu rity
	9573	ICR #:4054
	9574	Descriptio n:This API validates a VistALi nk user’s credential s for sign on to M.
	9575	Format:VAL IDAV^XUSRB (credentia l)
	9576	Input Para meters:cre dential:(r equired) A credentia l (typical ly the enc oded “Acce ss code;Ve rify code” string) t o use to a ttempt a s ignon for the curren t user.
	9577	Output:ret urns:Retur ns:
	9578	;Return R( 0)=DUZ, R( 1)=(0=OK, 1,2...=Can ’t sign on for some reason) ; R(2)=verif y needs ch anging, R( 3)=Message , R(4)=0, R(5)=msg c nt, R(5+n) ; R(R(5)+ 6)=# div u ser must s elect from , R(R(5)+6 +n)=div
	9579
	9580	$$DECRYP^X USRB1(): D ecrypt Str ing
	9581	Reference Type:Suppo rted
	9582	Category:S ignon/Secu rity
	9583	ICR #:2241
	9584	Descriptio n:This ext rinsic fun ction decr ypts a str ing that w as encrypt ed on a Cl ient syste m. This fu nction dec rypts a st ring that has been e ncrypted u sing the E ncrypt Del phi functi on supplie d by the R PC Broker, returning the decry pted strin g.
	9585	Format:$$D ECRYP^XUSR B1(encrypt ed_string)
	9586	Input Para meters:enc rypted_str ing:(requi red) Encry pted strin g to be de crypted.
	9587	Output:ret urns:Retur ns the dec rypted str ing.
	9588
	9589	$$ENCRYP^X USRB1(): E ncrypt Str ing
	9590	Reference Type:Suppo rted
	9591	Category:S ignon/Secu rity
	9592	ICR #:2240
	9593	Descriptio n:This ext rinsic fun ction encr ypts a str ing before transport to a Clie nt system, where it is decrypt ed. This f unction pe rforms enc ryption on the input string, r eturning t he encrypt ed string.
	9594	Format:$$E NCRYP^XUSR B1(string)
	9595	Input Para meters:str ing:(requi red) The i nput strin g to be en crypted.
	9596	Output:ret urns:Retur ns the enc rypted str ing.
	9597
	9598	$$HANDLE^X USRB4(): R eturn Uniq ue Session ID String
	9599	Reference Type:Suppo rted
	9600	Category:S ignon/Secu rity
	9601	ICR #:4770
	9602	Descriptio n:This ext rinsic fun ction retu rns a uniq ue Caché c luster str ing for a VistA syst em for use by Health eVet Deskt op applica tions. Thi s API was made avail able with Kernel pat ch XU8.0 395.
	9603	Format:$$H ANDLE^XUSR B4(“namesp ace”[,time tolive])
	9604	Input Para meters:“na mespace”:( required) This input parameter should st art with t he VistA s oftware na mespace. I n addition , users ca n add any additional applicati on/softwar e identifi ers.
	9605	timetolive :(optional ) This inp ut paramet er indicat es the num ber of day s that thi s handle i s availabl e for use. Possible values ran ge from 1 to 7. The default is 1. The ^X TMP global requires that the z ero node h old the sa ve through date. Thi s value is cleaned u p via the XQ82 routi ne (i.e., Clean old Job Nodes in XUTL op tion [XQ X UTL $J NOD ES]).
	9606	Output:ret urns:Retur ns the uni que Vista system Cac hé cluster string. T he value g enerated i ncludes th e data ent ered in th e namespac e input pa rameter an d $J and $ H. If this value is already de fined, a n ew value i s generate d.
	9607
	9608	Example
	9609	In this ex ample, we are creati ng a uniqu e session ID for the RPC Broke r namespac e (i.e., “ XWB”):
	9610	>S HDL=$$H ANDLE^XUSR B4(“XWB-CC OW”)
	9611
	9612	>W HDL
	9613	XWB-CCOW92 8-57785_0
	9614
	9615	When check ing the ^X TMP tempor ary global you would see:
	9616	^XTMP(“XWB -CCOW928-5 7785_0”,0) = 3050805 ^3050804
	9617
	9618	^XUVERIFY: Verify Ac cess and V erify Code s
	9619	Reference Type:Suppo rted
	9620	Category:S ignon/Secu rity
	9621	ICR #:1005 1
	9622	Descriptio n:This API validates Access an d Verify c odes. You can use it anytime w ithin an a pplication program t o verify t hat the pe rson using the syste m is the s ame person who signe d onto the system.
	9623	Format:^XU VERIFY
	9624	Make sure to perform the follo wing steps before ca lling this API:
	9625	NEW all no n-namespac ed variabl es.
	9626	Set all in put variab les.
	9627	Call the A PI.
	9628	Input Vari ables:%:(r equired) I f % equals :
	9629	A—Check th e Access c ode.
	9630	V—C heck t he Verify code.
	9631	AV—Check b oth the Ac cess and V erify code .
	9632	%DUZ:(requ ired) The user’s num ber (DUZ v alue).
	9633	Output Var iables:%:R eturns the following values:
	9634	2—Failure (the incor rect code was entere d).
	9635	1—Success (the corre ct code wa s entered) .
	9636	0—A questi on mark wa s entered.
	9637	-1—A caret (“^”) was entered.
	9638
	9639	$$CHECKAV^ XUVERIFY() : Check Ac cess/Verif y Codes
	9640	Reference Type:Suppo rted
	9641	Category:S ignon/Secu rity
	9642	ICR #:1005 1
	9643	Descriptio n:This ext rinsic fun ction chec ks an Acce ss/Verify code pair entered by the user (delimited by a semi -colon) an d returns whether or not it is a valid p air.
	9644	Format:$$C HECKAV^XUV ERIFY(acce ss_verify)
	9645	Input Para meters:acc ess_verify :(required ) This is a string c ontaining the Access and Verif y code pai r delimite d by a sem i-colon (i .e., Acces s code;Ver ify code).
	9646	Output:ret urns:Retur ns:
	9647	Internal E ntry Numbe r (IEN)—Co des are OK .
	9648	Zero (0)—C odes are n ot OK.
	9649
	9650	Example
	9651	>S X=$CHEC KAV^XUVERI FY(<Access and Verif y code str ing>)
	9652
	9653	String = A ccess code ;Verify co de
	9654	WITNESS^XU VERIFY(): Return IEN of Users with A/V C odes & Sec urity Keys
	9655	Reference Type:Contr olled Subs cription
	9656	Category:S ignon/Secu rity
	9657	ICR #:1513
	9658	Descriptio n:This API returns t he IEN of a user if he/she has an Access code, Ver ify code, and securi ty keys.
	9659	Format:WIT NESS^XUVER IFY(prefix ,keys)
	9660	Input Para meters:pre fix:String to put be fore the A ccess/Veri fy code pr ompt.
	9661	keys:Strin g of secur ity keys t he user mu st have.
	9662	Output:ret urns:Retur ns:
	9663	IEN (succe ssful)—The user has an Access code, Veri fy code, a nd securit y keys.
	9664	0 (failure )—The user does not have an Ac cess code, Verify co de, and se curity key s.
	9665
	9666	Example
	9667	>S Y=$$WIT NESS^XUVER IFY(“Cosig n”,“XUMGR” ) W !,Y
	9668
	9669	Cosign ACC ESS CODE: ********
	9670	Cosign VER IFY CODE: ********
	9671	2
	9672
	9673	GETPEER^%Z OSV: VistA Link—Get I P Address for Curren t Session
	9674	Reference Type:Contr olled Subs cription
	9675	Category:S ignon/Secu rity
	9676	ICR #:4056
	9677	Descriptio n:This API retrieves an IP add ress value for the c urrent ses sion, whic h is requi red as inp ut (i.e., XWBTIP inp ut variabl e) for the SETUP^XUS RB(): Vist ALink—Set Up User’s Partition in M API. The VistAL ink securi ty module calls this API.
	9678	Format:GET PEER^%ZOSV
	9679	Input Para meters:non e.
	9680	Output:ret urns:Retur ns the Int ernet Prot ocol (IP) address of the curre nt connect ed session to M.
	9681
	9682
	9683
	9684	Spooling: Developer Tools
	9685	Overview
	9686	In order f or an appl ication to spool rep orts, the applicatio n must cal l the Devi ce Handler to open t he spool d evice. If the applic ation fail s to close the devic e, the spo ol documen t is not a ccessible. The appli cation sho uld close the spool device by using D ^% ZISC. Furt hermore, q ueuing to the spoole r requires that the applicatio n invoke ^ %ZTLOAD wi th the pro per variab les define d.
	9687	The ZTIO i nput varia ble can be set to id entify how the devic e should b e opened. If incorre ctly set u p, the que ued task c ould fail to send re sults to t he spooler . If you h ave any do ubt about how to set ZTIO, you should le ave it und efined. ^% ZTLOAD can define ZT IO with th e appropri ate variab les from s ymbols lef t in the c urrent par tition fol lowing the last call to the De vice Handl er.
	9688	NOTE: The following code sampl es are not complete. They do n ot contain code to i ssue form feeds betw een pages of output. REF: For t he details of issuin g form fee ds, see th e “Form Fe eds” secti on in the “Special D evice Issu es” sectio n.
	9689	Figure 99: Spooling— Sending ou tput to th e spooler (and pre-d efining ZT IO)
	9690	SAMPLE ;S AMPLE ROUT INE
	9691	;
	9692	S %ZIS=“QM” D ^%ZIS G EXIT:POP
	9693	I $D(IO(“Q”) ) D D ^%Z TLOAD D HO ME^%ZIS K IO(“Q”) Q
	9694	.S ZTRTN=“DQ ^SAMPLE”,Z TDESC=“Sam ple Test r outine”
	9695	.S ZTIO=ION_ ”;”_IOST
	9696	.I $D(IO(“DO C”))#2,IO( “DOC”)]“” S ZTIO=ZTI O_“;”_IO(“ DOC”) Q
	9697	.I IOM S ZTI O=ZTIO_“;” _IOM
	9698	.I IOSL S ZT IO=ZTIO_“; ”_IOSL
	9699	DQ U IO W !,“TH IS IS YOUR REPORT”
	9700	W !,“LINE 2”
	9701	W !,“LINE 3”
	9702	D ^%ZISC
	9703	EXIT S: $D(ZTQUEUE D) ZTREQ=“ @” K VAR1, VAR2,VAR3 Q
	9704
	9705	Figure 100 : Spooling —Allowing output to go the spo oler (with out pre-de fining ZTI O)
	9706	SAMPLE ;S AMPLE ROUT INE
	9707	;
	9708	S %ZIS=“QM” D ^%ZIS G EXIT:POP
	9709	I $D(IO(“Q”) ) D Q
	9710	.S ZTRTN=“DQ ^SAMPLE”,Z TDESC=“Sam ple Test r outine”
	9711	.D ^%ZTLOAD D HOME^%ZI S K IO(“Q” ) Q
	9712	DQ U IO W !,“TH IS IS YOUR REPORT”
	9713	W !,“LINE 2”
	9714	W !,“LINE 3”
	9715	D ^%ZISC
	9716	EXIT S: $D(ZTQUEUE D) ZTREQ=“ @” K VAR1, VAR2,VAR3 Q
	9717
	9718	Applicatio n Programm ing Interf ace (API)
	9719	Several AP Is are ava ilable for developer s to work with spool ing. These APIs are described below.
	9720	DSD^ZISPL: Delete Sp ool Data F ile Entry
	9721	Reference Type:Contr olled Subs cription
	9722	Category:S pooling
	9723	ICR #:1092
	9724	Descriptio n:This API deletes S POOL DATA file (#3.5 19) entry following transfer o f data, to minimize consumptio n of data.
	9725	Format:DSD ^ZISPL
	9726	Input Para meters:non e.
	9727	Output:non e.
	9728
	9729	DSDOC^ZISP L: Delete Spool Docu ment File Entry
	9730	Reference Type:Contr olled Subs cription
	9731	Category:S pooling
	9732	ICR #:1092
	9733	Descriptio n:This API deletes t he SPOOL D OCUMENT fi le (#3.51) entry fol lowing tra nsfer of d ata, to mi nimize con sumption o f disk spa ce.
	9734	Format:DSD OC^ZISPL
	9735	Input Para meters:non e.
	9736	Output:non e.
	9737
	9738
	9739
	9740	TaskMan: D eveloper T ools
	9741	Overview
	9742	The TaskMa n API cons ists of se veral call able entry points an d an extri nsic varia ble. Use o f these ca lls makes the creati on, schedu ling, and monitoring of backgr ound proce ssing from within ap plications straightf orward.
	9743	Developers must avoi d directly setting i nformation into Task Man’s glob als to que ue tasks. In fact, t he SAC spe cifies tha t TaskMan’ s calls be used. The structure of the gl obals is n ot static; there is no commitm ent to sup port their current s tructure i n the futu re.
	9744	REF: For m ore inform ation on w hy and whe n to use T askMan to perform qu euing, see the “Task Man System Managemen t: Overvie w” section in the Ke rnel Syste ms Managem ent Guide.
	9745	How to Wri te Code to Queue Tas ks
	9746	Writing co de to queu e a task i s not diff icult; how ever, the coding mus t be done carefully and system atically. If you thi nk of it i n two part s, it is e asier to w rite. Thes e two part s are the queuer and the task:
	9747	Queuer—Som e code mus t invoke ^ %ZTLOAD to create an d schedule the task. This code is the qu euer. The most compl ex part of a queuer is determi ning which variables must be p assed on t o the task .In one ty pe of queu er, the pr ogram appl ication ma kes its ow n calls to ^%ZTLOAD to queue t asks. In t he other c ommon type of queuer , schedule d options, an option is schedu led to run as a task through t he OPTION SCHEDULING file (#19 .2); TaskM an itself takes care of the qu euing.
	9748	Task—Some code must perform th e actual w ork in the backgroun d. Sometim es the tas k shares c ode with a n equivale nt foregro und activi ty. Howeve r, remembe r that a q ueued task runs unde r special conditions that must be consid ered. For example, n o interact ive dialog ue with th e user is possible.
	9749	Usually, b oth pieces of code s hould be p lanned tog ether sinc e they int eract heav ily.
	9750	Queuers
	9751	As mention ed above, there are two common types of queuers:
	9752	Applicatio n code tha t itself a cts as the queuer by calling ^ %ZTLOAD.
	9753	Options th at are sch eduled (in which cas e, TaskMan itself ac ts as the queuer).
	9754	Calling ^% ZTLOAD to Create Tas ks
	9755	One common way to cr eate tasks is to cal l TaskMan’ s main API , ^%ZTLOAD . You can use ^%ZTLO AD interac tively, or non-inter actively.
	9756	REF: For m ore inform ation on q ueuing tas ks with ^% ZTLOAD, se e the “^%Z TLOAD: Que ue a Task” section.
	9757	Calling EN ^XUTMDEVQ to Create Tasks
	9758	The EN^XUT MDEVQ API encapsulat es the log ic to hand le both di rect print ing and qu euing in a single ca ll.
	9759	Creating T asks Using Scheduled Options
	9760	You can al so create options th at you ask the sites to schedu le on a re gular basi s. In this case, Tas kMan itsel f (rather than appli cation cod e) acts as the queue r. Site ma nagers use TaskMan t o queue op tions and can schedu le these o ptions to run again and again on some sp ecified sc hedule.
	9761	You should be carefu l because this creat es a great possibili ty for con fusion. Ob viously, s ome option s cannot b e schedule d, in the same way t hat some r outines ca nnot be qu eued. When you creat e options that shoul d be sched uled, you should:
	9762	Indicate w hether an option can be schedu led throug h TaskMan and, if so , the reco mmended fr equency of schedulin g. Do this using the DESCRIPTI ON field o f the opti on.
	9763	Indicate t he format of data to pass to t he schedul ed option via the TA SK PARAMET ERS field, if the op tion uses such data. Do this u sing the D ESCRIPTION field of the option .
	9764	Set the SC HEDULING R ECOMMENDED field of the option to YES. T his makes the option show up i n a Kernel report th at lists a ll options on the sy stem that should be scheduled.
	9765	Consider u sing a nam e for the option tha t reflects the fact that it is intended to be run only by Ta skMan, if you create such an o ption.
	9766	Give the o ption a pa rent (i.e. , attach i t to a men u). This p revents th e option f rom being deleted by Kernel’s Delete Unr eferenced Options (X Q UNREF’D OPTIONS) p urge optio n. If the option can not be use d interact ively, mak e sure tha t it is no t attached to a menu that is p art of a u ser’s menu tree. Ins tead, atta ch it to a menu that is not on any user’ s menu tre e. An exam ple is Ker nel’s ZTMQ UEUABLE OP TIONS. It is not in any user m enu tree. If you do not want t o create y our own me nu to be a parent of queueable options, you are al lowed to a ttach your option to Kernel’s ZTMQUEUABL E OPTIONS option and export ZT MQUEUABLE OPTIONS th rough KIDS ’ USE AS L INK FOR ME NU ITEMS a ction.
	9767	When you c reate opti ons that q ueue tasks but that cannot be scheduled themselves , you shou ld be espe cially cle ar in docu menting th is so that site mana gers does not try to schedule them.
	9768	Queued opt ions diffe r from oth er tasks i n only a f ew ways:
	9769	They may h ave an ent ry and exi t action a nd may set XQUIT in the entry action to avoid runn ing.
	9770	They can r un on a sc heduling c ycle as de fined by t he system manager.
	9771	They are d esigned ex plicitly f or the sys tem manage r to use, since the option use d to sched ule option s is avail able only to system managers.
	9772	They can b e better d ocumented than norma l tasks be cause the OPTION fil e (#19) en try provid es a place for a per manent des cription o f the task ’s purpose and behav ior (the D ESCRIPTION field).
	9773	If the opt ion is sch eduled reg ularly, da ta can be passed to your task from the O PTION SCHE DULING fil e’s (#19.2 ) TASK PAR AMETERS fi eld; the d ata is mad e availabl e to the t ask at run time in t he ZTQPARA M variable . The vari able is on ly defined if an ent ry is made in the TA SK PARAMET ERS field when the t ask is sch eduled. Th e format t hat is exp ected of i nformation entered i n the TASK PARAMETER S field sh ould be de scribed in the optio n’s DESCRI PTION fiel d.
	9774	You should describe scheduling recommend ations and the forma t, if any, for the T ASK PARAME TERS field (as well as in the option’s D ESCRIPTION field) in your soft ware appli cation ins tallation guide for all the qu eueable op tions, sin ce options are usual ly set on their sche dules shor tly after installati on.
	9775	Tasks
	9776	This secti on describ es informa tion about Tasks. It applies w hether the queuer th at queued the task w as a call to ^%ZTLOA D, or Task Man itself was runni ng the tas k because it was sch eduled in the OPTION SCHEDULIN G file (#1 9.2).
	9777	When you w rite a tas k, you cre ate an API that Task Man can ca ll to perf orm the wo rk. The su bmanager c alls the A PI you spe cify to ru n the task . The subm anager doe s more tha n pass you r task a f ew paramet ers, howev er; it cre ates an en tire speci alized env ironment f or the tas k, accordi ng to your specifica tions. The n the subm anager cal ls your AP I, at whic h point yo ur task be gins runni ng. When y our task q uits, cont rol passes back to t he submana ger.
	9778	The interf ace betwee n tasks an d submanag ers determ ines the s pecial pro blems you must solve and the f eatures yo u have ava ilable to do so. Thi s interfac e consists of two pa rts:
	9779	The enviro nment and tools that the subma nagers gua rantee to the tasks.
	9780	The respon sibilities of the ta sks themse lves.
	9781	Key Variab les and En vironment When Task is Running
	9782	All VistA processes run in a g uaranteed environmen t, with st andard var iables and devices a vailable t o the soft ware. The guaranteed environme nt for tas ks differs from that of foregr ound proce sses in so me ways, h owever. Th is reflect s the diff erences be tween the foreground and backg round, and the speci al service s provided by TaskMa n. The sub managers g uarantee t asks the f ollowing v ariables a nd other f eatures:
	9783	DT: While this usual ly designa tes the da te when a user signs on, here it contain s the date when the task first began run ning (in F ileMan for mat, of co urse).
	9784	DUZ(: The entire DUZ array (ex cept DUZ(“ NEWCODE”)) , as defin ed at the time of yo ur call to the Progr am Interfa ce, is alw ays passed to your t ask. If DU Z was not properly s et up at t hat time, then it is set to 0. If DUZ(0) was not p roperly se t up, then the subma nager atte mpts to lo ok it up u sing your DUZ variab le; if the lookup fa ils, it se ts DUZ(0)= “”. The su bmanager d oes the sa me thing w ith DUZ(2) .
	9785	IO*: All o f the IO v ariables d escribing the output device th at you rec eive are p assed to y ou. If you request n o output d evice, the n IO, IO(0 ), and ZTI O all equa l “”.
	9786	ZTDESC: Th is contain s the free -text desc ription of your task that you passed to the Progra m Interfac e.
	9787	ZTDTH: Thi s contains the date and time ( in $HOROLO G format) that you w anted your task to b egin runni ng. Becaus e delays f rom a numb er of sour ces can ma ke your ta sk begin l ate, this variable m ay be usef ul.
	9788	ZTIO: This contains your origi nal output device sp ecificatio ns.
	9789	ZTQUEUED: This varia ble is alw ays define d when you r task beg ins, and i s only def ined for b ackground tasks. Man y queued r outines ca n run eith er in the foreground or in the backgroun d. The onl y reliable way to de termine wh ich situat ion is cur rently the case is u sing the M code:
	9790	>IF $D(ZTQ UEUED)
	9791	ZTRTN: Thi s variable is the AP I that Tas kMan will DO to star t the task .
	9792	ZTSK: Ever y task is passed its internal number so that it ca n make use of the Pr ogram Inte rface.
	9793	Destinatio n: Using Z TUCI, ZTIO , and ZTCP U, you can request a specific UCI on a s pecific vo lume set a nd CPU nod e where yo ur task sh ould run. The locati on you req uest is wh ere the su bmanager c alls your API. Remem ber that t he SAC doe s not prot ect the Ta skMan name spaced inp ut variabl es to your task (e.g ., ZTIO, Z TSK, etc.) , however. The subma nagers gua rantee the ir values to the tas ks, but on ce you beg in running , their va lues may c hange. For example, the utilit ies you ca ll may alt er these v ariables, or your ow n code may . If your task needs to know t hese value s througho ut its exe cution, yo u should l oad them i nto your o wn namespa ced variab les, which you can t hen protec t.
	9794	Device: If you reque st an IO d evice for your task then, when the task starts, th e device i s open. Th e submanag er even is sues the U SE command for you a nd after y our task c ompletes, it properl y closes t he device for you. I f you leav e it open when you a re finishe d with it, the subma nager is a ble to rec ycle the d evice more efficient ly for use with othe r tasks.
	9795	Error Trap : The subm anager alw ays sets a n Error Tr ap before calling yo ur task. T his way, i f your tas k errors o ut, the su bmanager c an record that fact in the sys tem error log, in Ta skMan’s er ror log, a nd in the entry for your task in the TAS KS file (# 14.4).
	9796	Priority: Your task begins run ning with the priori ty specifi ed if you request on e.
	9797	Saved Vari ables: The submanage r passes a ny variabl es that th e queuer s aved using ZTSAVE. T hese act a s input va riables.
	9798	Tools: The task can rely upon the follow ing tools to assist it in meet ing its re sponsibili ties (as d escribed b elow):
	9799	$$S^%ZTLOA D
	9800	ZTSTOP
	9801	ZTQUEUED
	9802	ZTREQ
	9803	KILL^%ZTLO AD
	9804	^%ZTLOAD
	9805	Device Han dler
	9806	Resource d evices
	9807	SYNC FLAGs
	9808	Checking f or Stop Re quests
	9809	You should write tas ks in such a way tha t your tas ks honor s top reques ts. Since Kernel 7.0 , users ha ve been ab le to call the TaskM an User op tion to st op tasks t hat they s tarted. A task shoul d periodic ally check whether i t has been asked to stop and s hould grac efully shu t down whe n asked. T his involv es four st eps:
	9810	To check f or a stop request, t he task ca n execute the follow ing code:
	9811	>IF $$S^%Z TLOAD
	9812	If this ev aluates to TRUE, the user has asked the task to st op. This c heck shoul d occur pe riodically throughou t the task ; not so o ften as to increase significan tly the ta sk’s CPU u sage, but often enou gh that th e response time sati sfies the users. For example, a report p rintout mi ght check once per p age, while a massive data comp ilation mi ght check once every hundred o r even tho usand reco rds. Very short task s can choo se not to check at a ll.
	9813	The task m ay need to perform s ome intern al flaggin g or clean up. Stop r equests fr om a user rarely com e at ideal moments i n the over all algori thm of the task, and the task may need t o perform some work to prepare to quit.
	9814	The task n eeds to no tify the s ubmanager that it re sponded to the user’ s request to stop, s o that the submanage r can noti fy the use r. The tas k should u se the fol lowing cod e to do so :
	9815	>SET ZTSTO P=1
	9816	The ZTSTOP flag is p rocessed b y the subm anager whe n the task quits. Do not KILL this varia ble if you wish to p ass it bac k to the s ubmanager.
	9817	The task s hould then quit. Dep ending on how deeply within lo ops these stop reque st checks are made, it may tak e some pro cessing to work out of all loo ps and qui t on short notice. T he code ma y need to be adjuste d to allow for this kind of ex it.
	9818	In the end , checking for stop requests b enefits no t only the developer , by satis fying your users, bu t also the users the mselves by making th em feel mo re in cont rol, and t he system managers b y freeing them up fr om stoppin g tasks fo r users.
	9819	Purging th e Task Rec ord
	9820	According to the SA C, tasks h ave a resp onsibility to remove their own records f rom the TA SKS file ( #14.4) whe n they com plete. Thi s serves t wo purpose s. First, it helps k eep the TA SKS file s mall, whic h makes Ta skMan more efficient . Second, because an y tasks th at cause e rrors neve r reaches the final commands t o delete t he task’s record, su ch tasks r emain in t he TASKS f ile after they compl ete. This greatly as sists syst em managem ent staff in identif ying and t roubleshoo ting probl em tasks.
	9821	You have t wo methods to delete TASKS fil e (#14.4) entries:
	9822	ZTREQ outp ut variabl e
	9823	KILL^%ZTLO AD API
	9824	The recomm ended meth od, simple r than the other, is to use th e ZTREQ ou tput varia ble to ins truct the submanager to delete your task ’s record after it f inishes ru nning. Do this with the follow ing line o f M code:
	9825	>S ZTREQ=“ @”
	9826	Because th e submanag er does no t get this variable back until after you r task qui ts, you ca n set ZTRE Q anywhere within th e task and still ens ure your t ask does n ot delete its record if it err ors out.
	9827	NOTE: If y ou KILL of f the vari able befor e the task quits, th e submanag er does no t delete y our task.
	9828	The other method is to call KI LL^%ZTLOAD to delete the task’ s record. This solut ion has tw o disadvan tages. Fir st, the ZT SK input v ariable to KILL^%ZTL OAD needs to equal t he task nu mber of th e task to delete, wh ich may no t be the c ase if the task has called oth er utiliti es. The ta sk can sol ve this pr oblem by s aving off ZTSK at th e beginnin g and rest oring it p rior to ca lling KILL ^%ZTLOAD. Second, yo u must pla ce the cal l at the e nd of the task, just prior to quitting, ensuring t he record remains if the task encounters an error. This caus es problem s for task s that lac k a single exit poin t, but you can solve this by w riting a n ew API for the task that does the main b ody of the task, per forms the deletion, and then q uits.
	9829	Checking F or Backgro und Execut ion: ZTQUE UED
	9830	When you s hare code for both f oreground and backgr ound proce ssing, you often nee d the code to behave different ly under t he two sit uations. T he only re liable way to test w hether the code is r unning in the backgr ound is to check if the ZTQUEU ED variabl e is defin ed. It is only defin ed if the current ru nning job is a task. You can c heck for i ts existen ce, and th erefore, w hether the code is t ruly runni ng in the background , with the following M stateme nt:
	9831	>IF $D(ZTQ UEUED)
	9832	Post-Execu tion Comma nds: ZTREQ
	9833	Tasks can make the s ubmanager execute a certain li mited set of command s after th e tasks co mplete. Us e the ZTRE Q output v ariable to describe these post -execution commands.
	9834	The use of ZTREQ to delete a t ask’s reco rd has alr eady been discussed above. ZTR EQ can als o be used to edit an d/or resch edule the task.
	9835	To resched ule the ta sk to run again imme diately:
	9836	>S ZTREQ=“ ”
	9837	To requeue a modifie d version of your ta sk:
	9838	Use ZTREQ to specify how to mo dify the e xisting ta sk to run again. By optionally setting a ny of the various ^- pieces of ZTREQ, you can modif y that asp ect of how the resch eduled tas k runs. Th e purpose and format of each ^ -piece rou ghly corre sponds to the input variables of REQ^%ZT LOAD liste d below:
	9839	Table 31: TaskMan—ZT REQ piece and equiva lent REQ^Z TLOAD vari able
	9840	ZTREQ Piec e
	9841	Equivalent REQ^%ZTLO AD Variabl e
	9842	1
	9843	ZTDTH
	9844	2
	9845	ZTIO
	9846	3
	9847	ZTDESC
	9848	4^5
	9849	ZTRTN
	9850
	9851	All of the se ^-piece s in ZTREQ are optio nal; only set the pi eces that affect par ameters yo u want to change. Ho wever, tha t in the c ase of lea ving piece 2 NULL, t he task us es the sam e device t hat your t ask initia lly reques ted, which is not ne cessarily the device that it a ctually go t. To resc hedule the task to r un on the device you r task cur rently has , you must build up the ZTIO v alue using your IO v ariables.
	9852	To edit th e task wit hout actua lly resche duling it:
	9853	Set ^-piec e 1 to “@” , and set the other pieces to the values you want. This is e quivalent to setting ZTDTH=“@” , as descr ibed in th e REQ^%ZTL OAD: Reque ue a Task API. Remem ber, howev er, to inc lude at le ast one ca ret (“^”) in ZTREQ t o do this, since if ZTREQ=“@” the task i s deleted.
	9854	Remember t hat ZTREQ is not an input para meter that you pass to the sub manager; i t is an ou tput param eter from your task. The subma nager does its best to honor y our reques t, but if the reques t is impos sible, the n there is no way fo r you to f ind out. F or example , if you s pecify tha t the subm anager sho uld requeu e your tas k, then it attempts to do so; if it find s that you r task has been dele ted, there is no way for the s ubmanager to let you know. Whe n the subm anager can not honor your reque st, it ign ores it.
	9855	Calling ^% ZTLOAD wit hin a Task
	9856	Tasks can use all of the stand ard TaskMa n API call s. There i s no reaso n a task s hould not itself cal l the Task Man API to do requeu ing, delet ion, or an y of the o ther stand ard calls. The only way such c alls are s pecial is that they have many of the var iables the y need to pass alrea dy defined for them by the sub manager.
	9857	You should be carefu l to avoid interfere nce from t hese pre-d efined var iables; so metimes th e submanag er passes you the va lue you ne ed for the API call, but somet imes you n eed a diff erent one. For examp le, from w ithin a ta sk that ha s an IO de vice, to c all ^%ZTLO AD to queu e a task w ithout an IO device, you shoul d set ZTIO (to “”), because th e input va riable pas sed in by the subman ager may s till be de fined. Wit h a little care, the se kinds o f problems can easil y be antic ipated and prevented .
	9858	Calling th e Device H andler (^% ZIS) withi n a Task
	9859	The main D evice Hand ler API (^ %ZIS) by i tself is n ot designe d to open more than one I/O de vice beyon d the alre ady-open h ome device . Within a task, you are free to open on e addition al device (beyond th e home dev ice) using ^%ZIS. If you need to open mo re than on e device c oncurrentl y within a task, how ever, you should use Kernel’s multiple d evice APIs (OPEN^%ZI SUTL, USE^ %ZISUTL, a nd CLOSE^% ZISUTL).
	9860	Long Runni ng Tasks—W riting Two -step Task s
	9861	A situatio n you shou ld always consider i s how to d eal with j obs that t ake a long time to g ather data and then print a re port of th at data. I f you writ e this as a single j ob that bo th gathers and print s data, an y requeste d IO devic e that is eventually used to p rint that data sits idle for a long peri od of time . Thus, th e IO devic e is unuse d and unav ailable to any other tasks dur ing that e ntire peri od of time it takes to gather the data f or your re port.
	9862	If you wri te the tas k to start without a device, a nd to call the ^%ZIS : Standard Device Ca ll API to open the d evice when the repor t is ready , two diff erent prob lems occur :
	9863	First, if the device is heavil y used by tasks, the n this tas k may neve r get a ch ance to op en the dev ice; TaskM an keeps i t busy wit h other ta sks.
	9864	Second, if the task does manag e somehow to grab th e device a way from T askMan, it interfere s with the fair dist ribution o f resource s, potenti ally runni ng ahead o f other ta sks that h ave been w aiting lon ger.
	9865	One way ar ound this problem is to queue the task t o a spool device. Sp ool device s are alwa ys availab le, which solves the problem o f tying up a device. However, some syste m managers discourag e use of s poolers, b ecause of the possib ility for disk crash es resulti ng from us ers who se nd excessi vely large reports t o the spoo ler.
	9866	Therefore, the best solution t o this pro blem invol ves splitt ing the jo b into two separate tasks:
	9867	Gather—The first tas k runs wit hout a dev ice, gathe rs and gen erates the report da ta in the ^XTMP glob al, and sc hedules th e second t ask (Print ).
	9868	Print—The second tas k runs wit h the IO d evice and prints the report da ta generat ed by the first task (Gather).
	9869	In order t o perform these two separate b ut associa ted tasks, Kernel pr ovides the following APIs:
	9870	$$QQ^XUTMD EVQ(): Dou ble Queue— Direct Que uing in a Single Cal l—This API creates t he Gather and the Pr int tasks. The gathe r task is scheduled to run, wh ile the pr int task i s not sche duled.
	9871	$$REQQ^XUT MDEVQ(): S chedule Se cond Part of a Task— At the end of the Ga ther task, it invoke s the $$RE QQ^XUTMDEV Q API to s chedule th e Print ta sk.
	9872	Long Runni ng Tasks—U sing ^%ZIS
	9873	As an alte rnative to splitting the job i nto two se parate tas ks an inte ractive ca ll can be made to ^% ZIS to all ow the use r to selec t the outp ut device without op ening it. The gather data port ion of the job can t hen procee d without tying up t he output device. Wh en the job is ready to print i t can open the outpu t device u sing the v ariables t hat were s aved when the ^%ZIS device sel ection cal l was made .
	9874	To allow f or selecti on of the output dev ice withou t actually opening i t make sur e the ^%ZI S input va riable %ZI S contains “N”.
	9875	Some of th e variable s returned by the de vice selec tion call to ^%ZIS n eed to be saved for use when t he device open call is made. T hese inclu de:
	9876	IO
	9877	IO(“DOC”),
	9878	IOM
	9879	ION
	9880	IOSL
	9881	If IO(“Q”) is 1 queu ing has be en selecte d and your code shou ld handle that and t ake care o f the queu ing.
	9882	The follow ing code e xcerpt sho ws the bas ic structu re for all owing the user to se lect wheth er a job i s queued o r not and the output device to use.
	9883	Figure 101 : TaskMan— Sample cod e allowing users to select whe ther a job is queued or not an d the outp ut device to use
	9884	N POP,%ZIS
	9885	S %ZIS=“NQ”
	9886	W !
	9887	D ^%ZIS
	9888	I POP G EXI T
	9889	I ION=(“HOS T FILE SER VER”)!(ION =“P-MESSAG E-HFS”) S SAVEHFIO=I O
	9890	S SAVEIOP=I ON_”;”_$G( IOST)_”;”_ $G(IO(“DOC ”))_”;”_$G (IOM)_”;”_ $G(IOSL)
	9891	;
	9892	I IO(“Q”) D Q
	9893	. ;Queue the report.
	9894	. ;If ZTIO i s not expl icitly set to null t hen %ZTLOA D will ope n
	9895	. ;the devic e.
	9896	. S ZTIO=“”
	9897	.
	9898	.
	9899	.
	9900	. D ^%ZTLO AD
	9901	.
	9902	.
	9903	.
	9904	I ‘IO(“Q”) D Q
	9905	. ;Run the r eport.
	9906	.
	9907	.
	9908	.
	9909
	9910	When it is time to p rint, the output dev ice can be opened us ing the va riables th at were sa ved.
	9911	Figure 102 : TaskMan— Sample cod e printing to a devi ce using s aved varia bles
	9912	N IOP,POP,V DUZ,XMDUZ, XMQUIET,XM SUB,XMY,%Z IS
	9913	; Check for output to p-message. TaskMan w ill automa tically co py
	9914	; ^TMP(“XM-M ESS”,$J) t o the task ed job.
	9915	I $D(^TMP(“ XM-MESS”,$ J)) D
	9916	. S XMQUIET =1
	9917	. S XMDUZ=$ G(^TMP(“XM -MESS”,$J, “XMHOST”,“ XMINSTR”,“ FROM”))
	9918	. I XMDUZ=“ ” S XMDUZ= ^TMP(“XM-M ESS”,$J,“X MHOST”,“XM DUZ”)
	9919	. S XMSUB=^ TMP(“XM-ME SS”,$J,“XM HOST”,“XMS UB”)
	9920	. S VDUZ=“”
	9921	. F S VDUZ =$O(^TMP(“ XM-MESS”,$ J,“XMY”,VD UZ)) Q:VDU Z=“” S XM Y(VDUZ)=“”
	9922	. I $D(XMY( DUZ)),$D(^ TMP(“XM-ME SS”,$J,“XM HOST”,“XMI NSTR”,“SEL F BSKT”)
	9923	) S XMY(DU Z,0)=^TMP( “XM-MESS”, $J,“XMHOST ”,“XMINSTR ”,“SELF BS KT”)
	9924	S IOP=SAVEI OP
	9925	I $D(SAVEHF IO) S %ZIS (“HFSNAME” )=SAVEHFIO
	9926	D ^%ZIS
	9927	I POP G EXI T
	9928	U IO
	9929
	9930	If p-messa ge was sel ected then ^TMP(“XM- MESS”,$J) is defined and conta ins all th e informat ion requir ed to deli ver the me ssage. Set ting XMQUI ET=1 stops interacti ve process ing by Mai lMan. XMDU Z is the s ender and XMSUB is t he subject . The VDUZ loop is t he list of people to which the user has chosen to send the m essage. Fi nally, the check for “SELF BSK T” is to d etermine i f the user has selec ted a part icular bas ket to whi ch the mes sage is to be delive red.
	9931	Using SYNC FLAGs to Control Se quences of Tasks
	9932	You can us e SYNC FLA Gs togethe r with res ource type devices w hen queuin g through ^%ZTLOAD, as a mecha nism to en sure seque ntial proc essing of a series o f tasks. T he mechani sm also en sures that subsequen t tasks in the serie s do not r un if a pr evious tas k errors o ut or comp letes unsu ccessfully .
	9933	A SYNC FLA G is a uni que, arbit rary FREE TEXT name you use as an identi fying flag . You use SYNC FLAGs in conjun ction with resource devices; w hen paired with a pa rticular r esource de vice, the pairing is called a SYNC FLAG pair.
	9934	The SYNC F LAG pair t ies all ta sks that h ave reques ted the sa me SYNC FL AG and the same reso urce toget her. If a task in a group of t asks is ru nning, all other tas ks queued with the s ame SYNC F LAG pair h ave to wai t until th e running task has c ompleted. If one tas k in the s eries does not finis h successf ully, then all other tasks usi ng the sam e SYNC FLA G pair wai ts.
	9935	To build a series of tasks, yo u need to choose a r esource de vice and q ueue the e ntire seri es of task s in the s ame order that they should run , through ^%ZTLOAD. Use the ZT IO variabl e to queue all tasks in the se ries to th e same res ource devi ce. Use th e ZTSYNC p arameter t o use the same SYNC FLAG for e ach task i n the seri es. TaskMa n then run s the seri es of task s in the s ame order that they were queue d.
	9936	The SYNC F LAG pair u niquely id entifies o ne group o f tasks us ing one re source dev ice. TaskM an builds a SYNC FLA G pair by concatenat ing the re quested re source (fr om the ^%Z TLOAD ZTIO input var iable) wit h the name of the SY NC FLAG (f rom the ^% ZTLOAD ZTS YNC input variable).
	9937	In any giv en task in the serie s of tasks , you indi cate that the task c ompleted s uccessfull y by KILLi ng the ZTS TAT variab le or sett ing it to 0. Otherwi se, no sub sequent ta sks is abl e to run.
	9938	The follow ing descri bes how us ing SYNC F LAG pairs ensures se quential p rocessing of a serie s of tasks :
	9939	When a tas k is queue d through ^%ZTLOAD, if the ZTS YNC is def ined, then the SYNC FLAG defin ed by ZTSY NC is save d with tha t task.
	9940	When TaskM an is read y to start the task, after it is able to allocate the resour ce device to which i t was queu ed, it che cks whethe r the SYNC FLAG pair (Resource _SYNC FLAG ) exists i n the TASK SYNC FLAG file (#14 .8).
	9941	If the SYN C FLAG pai r does not exist in the TASK S YNC FLAG f ile (#14.8 ), TaskMan creates a n entry fo r the SYNC FLAG pair in the TA SK SYNC FL AG file (# 14.8) and starts the task.
	9942	If, on the other han d, the SYN C FLAG pai r already exists in the TASK S YNC FLAG f ile (#14.8 ), then an y task req uiring the same SYNC FLAG has to wait un til the co rrespondin g entry in the TASK SYNC FLAG file (#14. 8) is dele ted.
	9943	If the tas k was able to start, the varia ble ZTSTAT is set to “1” in th e running task.
	9944	To indicat e success (e.g., tha t the seri es of task s should c ontinue), you must K ILL ZTSTAT or set it to zero. In this ca se, when y our task c ompletes, the SYNC F LAG pair f or that ta sk is clea red.
	9945	To indicat e failure (e.g., tha t the seri es of task s should n ot continu e) leave Z TSTAT set to 1.
	9946	When the t ask comple tes, TaskM an checks to see the value of ZTSTAT. If ZTSTAT is set to ze ro (0) or not define d, TaskMan deletes t he SYNC FL AG pair en try in the TASK SYNC FLAG file (#14.8). This allow s any futu re tasks i n the seri es to run.
	9947	If, on the other han d, ZTSTAT is left wi th a posit ive value, the task is assumed to have h ad some ki nd of erro r. In this case, the value of ZTSTAT is saved in t he STATUS field of t he SYNC FL AG pair en try, and t he entry i n the TASK SYNC FLAG file (#14 .8) is not deleted. Subsequent jobs in t he series are preven ted from r unning.
	9948	If the tas k errors o ut, the SY NC FLAG pa ir entry i s also lef t in the T ASK SYNC F LAG file ( #14.8), pr eventing s ubsequent jobs in th e series f rom runnin g. TaskMan puts a me ssage in t he STATUS field, say ing that t he task st opped due to an erro r.
	9949	Direct Mod e Utilitie s
	9950	You can us e TaskMan’ s direct m ode utilit ies from b oth the Ma nager and Production UCIs. Dev elopers ca nnot call them from applicatio ns, howeve r.
	9951	>D ^ZTMB: Start Task Man
	9952	This utili ty can be used to st art TaskMa n for the first time since sys tem startu p. As part of this s tartup, an y tasks sc heduled to begin at system sta rtup are f ired off.
	9953	>D RESTART ^ZTMB: Res tart TaskM an
	9954	This utili ty restart s TaskMan. RESTART^Z TMB, unlik e ^ZTMB, d oes not fi re off the startup t asks and s hould be u sed whenev er the sta rtup tasks have alre ady been i nitiated. The Restar t TaskMan option use s this ent ry point.
	9955	>D ^ZTMCHK : Check Ta skMan’s En vironment
	9956	This utili ty provide s the same functiona lity as th e Check Ta skman’s En vironment option but from Prog rammer mod e.
	9957	>D RUN^ZTM KU: Remove Taskman f rom WAIT S tate Optio n
	9958	This utili ty provide s the same functiona lity as th e Remove T askman fro m WAIT Sta te option but from P rogrammer mode.
	9959	>D STOP^ZT MKU: Stop Task Manag er Option
	9960	This utili ty provide s the same functiona lity as th e Stop Tas k Manager option but from Prog rammer mod e.
	9961	>D WAIT^ZT MKU: Place Taskman i n a WAIT S tate Optio n
	9962	This utili ty provide s the same functiona lity as th e Place Ta skman in a WAIT Stat e option, but from P rogrammer mode.
	9963	>D ^ZTMON: Monitor T askMan Opt ion
	9964	This utili ty provide s the same functiona lity as th e Monitor Taskman op tion, but from Progr ammer mode .
	9965	Applicatio n Programm ing Interf ace (API)
	9966	Several AP Is are ava ilable for developer s to work with TaskM an. These APIs are d escribed b elow.
	9967	TOUCH^XUSC LEAN: Noti fy Kernel of Tasks t hat Run 7 Days or Lo nger
	9968	Reference Type:Suppo rted
	9969	Category:T askMan
	9970	ICR #:1005 2
	9971	Descriptio n:This API notifies Kernel of any tasks that run 7 days or l onger. If a task app ears to ha ve been ru nning long er than 7 days, Kern el assumes that it r eally is n ot running anymore a nd KILLs o ff its tem p global a nd user st ack.
	9972	If your ta sk legitim ately runs more than 7 days, y our task s hould call the TOUCH ^XUSCLEAN API once a day to no tify Kerne l. This AP I sets ^XU TL(“XQ”,$J ,“KEEPALIV E”)=$H.
	9973	If Kernel sees this node, and $H is less than 7 da ys ago, Ke rnel leave s your tas k alone, u nless it d etermines that your task is re ally dead. If $H is more than 7 days ago , Kernel a ssumes you r task is dead and K ILLs the t emp global and user stack for that task.
	9974	There are no inputs or outputs to this A PI.
	9975	Format:TOU CH^XUSCLEA N
	9976	Input Para meters:non e.
	9977	Output:non e.
	9978
	9979	$$DEV^XUTM DEVQ(): Fo rce Queuin g—Ask for Device
	9980	Reference Type:Suppo rted
	9981	Category:T askMan
	9982	ICR #:1519
	9983	Descriptio n:This ext rinsic fun ction enca psulates t he logic t o handle d irect (FOR CED) queui ng in a si ngle call and ask us ers for a device. Th is API was added wit h Kernel p atch XU8. 0275.
	9984	Format:$$D EV^XUTMDEV Q(ztrtn[,z tdesc][,%v ar][,%voth ][,%zis][, iop][,%wr] )
	9985	Input Para meters:ztr tn:(requir ed) The AP I that Tas kMan will DO to star t the task (job). Yo u can spec ify it as “LABEL^ROU TINE” or “ ^ROUTINE” or “ROUTIN E”.
	9986	ztdesc:(op tional) Ta sk descrip tion, up t o 200 char acters des cribing th e task, wi th the sof tware appl ication na me at the front. Def ault to na me of [tag ]^routine.
	9987	%var:(opti onal) ZTSA VE values for the ta sk. Single value or passed by reference, this is u sed to S Z TSAVE(). I t can be a string of variable names sepa rated by “ ;”. Each ; -piece is used as a subscript in ZTSAVE.
	9988	%voth:(opt ional) Pas sed by ref erence, %v oth(sub)=“ ” or expli cit value sub—this i s any othe r %ZTLOAD variable b esides ZTR TN, ZTDESC , ZTIO, ZT SAVE. For example:
	9989	%VOTH(“ZTD TH”)=$H
	9990	%zis:(opti onal) Defa ult value “MQ”. Pass ed by refe rence, sta ndard %zis variable array for calling th e Device H andler.
	9991	iop:(optio nal) The I OP variabl e as defin ed in Kern el’s Devic e Handler.
	9992	%wr:(optio nal) If %W R>0 then w rite text to the scr een as to whether or not the q ueuing was successfu l.
	9993	Output:ret urns:Retur ns:
	9994	0—If run z trtn witho ut queuing .
	9995	-1—If unsu ccessful d evice call or failed the %ZTLO AD call.
	9996
	9997	Example
	9998	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so y ou divide the job in to two tas ks. The fi rst task g athers the informati on, and th e second t ask prints it. Use t he $$DEV^X UTMDEVQ AP I to selec t the devi ce and que ue up the print task , and the $$NODEV^XU TMDEVQ(): Force Queu ing—No Dev ice Select ion API to schedule the gather task. Use the REQ^% ZTLOAD: Re queue a Ta sk API to schedule t he print t ask when t he gather task finis hes.
	9999	NOTE: You can also u se the $$R EQQ^XUTMDE VQ(): Sche dule Secon d Part of a Task API to schedu le the pri nt task.
	10000	Figure 103 : $$DEV^XU TMDEVQ API —Example: Sample cod e
	10001	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10002	; ;1.1
	10003	DEV ;
	10004	N ARH,ARHZT SK,X
	10005	; The user d oesn’t kno w it, but he’s actua lly queuin g the seco nd task,
	10006	; the “print ” portion of the job . The onl y question the user will be
	10007	; asked is t o select t he device.
	10008	S ARH(“ZTDT H”)=“@” ;D on’t sched ule the ta sk to run, we’ll do it later.
	10009	; In the fol lowing, th e “Q” sets IOP=Q, wh ich forces queuing.
	10010	S X=$$DEV^X UTMDEVQ(“P RINT^ARHBQ Q”,“ARHB P rint”,,.AR H,,“Q”,1)
	10011	W !,“X=”,X
	10012	Q :X<1
	10013	N ARH
	10014	; Now queue the first task, the “gather” p ortion of the job. The user
	10015	; won’t be a sked any q uestions.
	10016	S ARHZTSK=X ; Save th e ZTSK num ber of the “print” t ask.
	10017	S ARH(“ZTDT H”)=$H ; F orce the t ask to sta rt now.
	10018	; To ask the user the start time , comment out the ab ove line.
	10019	S X=$$NODEV ^XUTMDEVQ( “GATHER^AR HBQQ”,“ARH B Gather”, “ARHZTSK”, .ARH,1)
	10020	W !,“X=”,X
	10021	Q
	10022
	10023	EN^XUTMDEV Q(): Run a Task (Dir ectly or Q ueued)
	10024	Reference Type:Suppo rted
	10025	Category:T askMan
	10026	ICR #:1519
	10027	Descriptio n:This API encapsula tes the lo gic to han dle both d irect prin ting and q ueuing in a single c all.
	10028	EN^XUTMDEV Q calls ^% ZIS to que ry the use r for devi ce selecti on. The us er can cho ose a devi ce on whic h to run t he job dir ectly or c hoose to q ueue the j ob.
	10029	After call ing ^%ZIS, EN^XUTMDE VQ looks t o see if t he queuing was chose n. If so, EN^XUTMDEV Q uses the values fr om the ztr tn, ztdesc , and ztsa ve input p arameters to queue t he job to the chosen device. I f the user did not c hoose to q ueue, EN^X UTMDEVQ ru ns the job directly using the ztrtn inpu t paramete r. Thus, E N^XUTMDEVQ provides a simple w ay to faci litate bot h queuing and runnin g a job di rectly.
	10030	If the IOP variable is defined before ca lling EN^X UTMDEVQ, i t has the same effec t as it do es if defi ned before a ^%ZIS c all.
	10031	If the ZTP RI or ZTKI L variable s are defi ned before calling E N^XUTMDEVQ , they has the same effect as they do if defined b efore an ^ %ZTLOAD ca ll. Other ^%ZTLOAD i nput varia bles have no effect, however.
	10032	You do not need to “ USE IO” in the routi ne specifi ed in the ztrtn inpu t paramete r; IO is t he current device, w hether the job is qu eued or ru n directly . Also, yo u do not n eed to pas s “Q” in t he top-lev el of the %ZIS input array; if the top-l evel of th e array do es not con tain “Q”, “Q” is app ended to i t (to allo w queuing) .
	10033	Format:EN^ XUTMDEVQ(z trtn,ztdes c,.ztsave[ ,.%zis][,r etztsk])
	10034	Input Para meters:ztr tn:(requir ed) The AP I that Tas kMan will DO to star t the task . You can specify it as “LABEL ^ROUTINE” or “^ROUTI NE” or “RO UTINE”.
	10035	ztdesc:(re quired) Ta sk descrip tion, up t o 200 char acters des cribing th e task, wi th the sof tware appl ication na me at the front.
	10036	.ztsave:(r equired) P ass by ref erence. Se t up this array in t he same fo rmat as th e ztsave i nput array is set up for the ^ %ZTLOAD Ta skMan API. The array you set u p in ztsav e is passe d directly as ztsave to TaskMa n if the u ser choose s to queue the job.
	10037	.%zis:(opt ional) Pas s by refer ence. Stri ng contain ing input specificat ions for t he Device Handler. S et up the array in t he same wa y as the % ZIS array is set up for the ^% ZIS: Stand ard Device Call API. The array you set u p in the % zis input parameter is passed directly a s %ZIS to the Device Handler.
	10038	All %zis s ubscripts from the r egular ^%z is call (“ A”, “B”, “ HFSMODE”, etc.) can be passed in the %zi s input ar ray.
	10039	retztsk:(o ptional) T his is the return ta sk number (i.e., zts k). Put a number in this param eter, such that $G(r etztsk), t hen ztsk e xists as a n output v ariable. O therwise, ztsk does not exist as an outp ut variabl e.
	10040	Output:zts k:If a num ber is ent ered in th e retztsk input para meter, the task numb er assigne d to a tas k is retur ned.
	10041
	10042	Example
	10043	Figure 104 : EN^XUTMD EVQ API—Sa mple repor t
	10044	ZZYZOPT ;ISC-SF/ doc
	10045	;;1.0 ;;
	10046	EN ;
	10047	N ZZE N K X,DIC S DIC=9.6, DIC(0)=“AE MO” D ^DIC
	10048	Q:+Y’ >0 S ZZEN =+Y
	10049	;
	10050	K ZTS AVE S ZTSA VE(“ZZEN”) =“”
	10051	D EN^ XUTMDEVQ(“ P^ZZYZOPT” ,“Print fr om BUILD F ile”,.ZTSA VE)
	10052	Q
	10053	P ;
	10054	; cod e for prin tout
	10055	;
	10056	W !,“ Here goes the body o f the repo rt!”
	10057	W !,“ ZZEN = ”,Z ZEN
	10058	Q
	10059
	10060	$$NODEV^XU TMDEVQ(): Force Queu ing—No Dev ice Select ion
	10061	Reference Type:Suppo rted
	10062	Category:T askMan
	10063	ICR #:1519
	10064	Descriptio n:This ext rinsic fun ction enca psulates t he logic t o handle d irect (FOR CED) queui ng in a si ngle call and does n ot ask use rs for a d evice. Thi s API was added with Kernel pa tch XU8.0 275.
	10065	Format:$$N O DEV^XUTM DEVQ(ztrtn [,ztdesc][ ,%var][,%v oth][,%wr] )
	10066	Input Para meters:ztr tn:(requir ed) The AP I that Tas kMan will DO to star t the task (job). Yo u can spec ify it as “LABEL^ROU TINE” or “ ^ROUTINE” or “ROUTIN E”.
	10067	ztdesc:(op tional) Ta sk descrip tion, up t o 200 char acters des cribing th e task, wi th the sof tware appl ication na me at the front. Def ault to na me of [tag ]^routine.
	10068	%var:(opti onal) ZTSA VE values for the ta sk. Single value or passed by reference, this is u sed to S Z TSAVE(). I t can be a string of variable names sepa rated by “ ;”. Each ; -piece is used as a subscript in ZTSAVE.
	10069	%voth:(opt ional) Pas sed by ref erence, %v oth(sub)=“ ” or expli cit value sub—this i s any othe r %ZTLOAD variable b esides ZTR TN, ZTDESC , ZTIO, ZT SAVE. For example:
	10070	%VOTH(“ZTD TH”)=$H
	10071	%wr:(optio nal) If %W R>0 then w rite text to the scr een as to whether or not the q ueuing was successfu l.
	10072	Output:ret urns:Retur ns:
	10073	> 0—Succes sful; Task # (number of the jo b).
	10074	-1—Unsucce ssful; If failed, th e %ZTLOAD call.
	10075
	10076	Example
	10077	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so y ou divide the job in to two tas ks. The fi rst task g athers the informati on, and th e second t ask prints it. Use t he $$DEV^X UTMDEVQ(): Force Que uing—Ask f or Device API to sel ect the de vice and q ueue up th e print ta sk, and th e $$NODEV^ XUTMDEVQ A PI to sche dule the g ather task . Use the REQ^%ZTLOA D: Requeue a Task AP I to sched ule the pr int task w hen the ga ther task finishes.
	10078	NOTE: You could also use the $ $REQQ^XUTM DEVQ(): Sc hedule Sec ond Part o f a Task A PI to sche dule the p rint task.
	10079	Figure 105 : $$NODEV^ XUTMDEVQ A PI—Sample code
	10080	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10081	; ;1.1
	10082	DEV ;
	10083	N ARH,ARHZT SK,X
	10084	; The user d oesn’t kno w it, but he’s actua lly queuin g the seco nd task,
	10085	; the “print ” portion of the job . The onl y question the user will be
	10086	; asked is t o select t he device.
	10087	S ARH(“ZTDT H”)=“@” ;D on’t sched ule the ta sk to run, we’ll do it later.
	10088	; In the fol lowing, th e “Q” sets IOP=Q, wh ich forces queuing.
	10089	S X=$$DEV^X UTMDEVQ(“P RINT^ARHBQ Q”,”ARHB P rint”,,.AR H,,”Q”,1)
	10090	W !,“X=”,X
	10091	Q :X<1
	10092	N ARH
	10093	; Now queue the first task, the “gather” p ortion of the job. The user
	10094	; won’t be a sked any q uestions.
	10095	S ARHZTSK=X ; Save th e ZTSK num ber of the “print” t ask.
	10096	S ARH(“ZTDT H”)=$H ; F orce the t ask to sta rt now.
	10097	; To ask the user the start time , comment out the ab ove line.
	10098	S X=$$NODEV ^XUTMDEVQ( “GATHER^AR HBQQ”,“ARH B Gather”, “ARHZTSK”, .ARH,1)
	10099	W !,“X=”,X
	10100	Q
	10101
	10102	$$QQ^XUTMD EVQ(): Dou ble Queue— Direct Que uing in a Single Cal l
	10103	Reference Type:Suppo rted
	10104	Category:T askMan
	10105	ICR #:1519
	10106	Descriptio n:This ext rinsic fun ction enca psulates t he logic t o handle d irect queu ing in a s ingle call . This API was added with Kern el Patches XU8.027 5 and upda ted with K ernel patc h XU8.03 89. This e xtrinsic f unction do es a doubl e queuing:
	10107	Queue up t he second task to a device, bu t do not s chedule th e task in TaskMan.
	10108	Queue up t he first t ask to ZTI O=“” and s chedule it .
	10109	If it take s a long t ime to gat her and pr int data, users shou ld split t he job int o two task s:
	10110	Gather Dat a—The firs t task gat hers the d ata.
	10111	Print Data —The secon d task pri nts the da ta.
	10112	Separating the data- gathering task from the data p rint task helps avoi d unnecess arily tyin g up a pri nter while large amo unts of da ta are gat hered.
	10113	The task n umber of t he second task (i.e. , print da ta) is add ed to the saved vari ables with the name XUTMQQ. Th is makes i t easier t o schedule the secon d task whe n the firs t task (i. e., gather data) has finished.
	10114	To schedul e the seco nd task to run at th e end of t he first t ask, you m ust call t he $$REQQ^ XUTMDEVQ() : Schedule Second Pa rt of a Ta sk API.
	10115	Format:$$Q Q^XUTMDEVQ (%rtn[,%de sc][,%var1 ][,%voth1] [,%zis][,i op][,%wr], %rtn2[,%de sc2][,%var 2][,%voth2 ])
	10116	Input Para meters:%rt n:(require d) First t ask that T askMan run s, usually a search and build sorted dat a type pro cess (i.e. , gather d ata). The API that T askMan wil l DO to st art the ta sk. You ca n specify it as “LAB EL^ROUTINE ” or “^ROU TINE” or “ ROUTINE”. [tag]^rout ine that T askMan run s.
	10117	%desc:(opt ional) Fir st task de scription, up to 200 character s describi ng the tas k, with th e software applicati on name at the front . Defaults to name o f [tag]^ro utine.
	10118	%var1:(opt ional) ZTS AVE values for the f irst task. Single va lue or pas sed by ref erence, th is is used to SET ZT SAVE(). It can be a string of variable n ames separ ated by “; ”. Each ;- piece is u sed as a s ubscript i n ZTSAVE.
	10119	%voth1:(op tional) Fi rst task o ther param eter. Pass ed by refe rence, %vo th(sub)=“” or explic it value s ub—this is any other %ZTLOAD v ariable be sides ZTRT N, ZTDESC, ZTIO, ZTS AVE. For e xample:
	10120	%VOTH(“ZTD TH”)=$H
	10121	%zis:(opti onal) Defa ult value “MQ”. Pass ed by refe rence, sta ndard %ZIS variable array for calling th e Device H andler. Ex cept for o ne differe nce, the s econd task of the jo b is taske d to this device cal l.
	10122	Exception:
	10123	IF $D(%ZIS )=0 then d efault val ue is “MQ” and call the Device Handler.
	10124	IF $D(%ZIS )=1,%ZIS=“ ” then que ue the sec ond task a lso with Z TIO=“” (i. e., do not do the De vice Handl er call).
	10125	iop:(optio nal) The I OP variabl e as defin ed in Kern el’s Devic e Handler. Default v alue “Q”—i f IOP is p assed and IOP does n ot start w ith “Q;” t hen “Q;” i s added.
	10126	%wr:(optio nal) If %W R>0 then w rite text to the scr een as to whether or not the q ueuing was successfu l.
	10127	%rtn2:(req uired) Sec ond task t hat TaskMa n runs, us ually a pr int proces s (i.e., p rint data) .The API t hat TaskMa n will DO to start t he task. Y ou can spe cify it as “LABEL^RO UTINE” or “^ROUTINE” or “ROUTI NE”.
	10128	%desc2:(op tional) Se cond task descriptio n, up to 2 00 charact ers descri bing the t ask, with the softwa re applica tion name at the fro nt. Defaul t to name of [tag]^r outine.
	10129	%var2:(opt ional) ZTS AVE values for the s econd task . Single v alue or pa ssed by re ference, t his is use d to S ZTS AVE(). It can be a s tring of v ariable na mes separa ted by “;” . Each ;-p iece is us ed as a su bscript in ZTSAVE.
	10130	If %var1 i s not pass ed and $D( %VAR), the n also sen d %VAR dat a to the s econd task .
	10131	If $D(%VAR 1), then d o not send %VAR data to the se cond task.
	10132	%voth2:(op tional) Se cond task other para meter, usu ally not n eeded. Pas sed by ref erence, %v oth(sub)=“ ” or expli cit value sub—this i s any othe r %ZTLOAD variable b esides ZTR TN, ZTDESC , ZTIO, ZT SAVE. For example:
	10133	%VOTH(“ZTD TH”)=$H
	10134	NOTE: If % voth1(“ZTD TH”) is pa ssed, it i s ignored as it is n ecessary t o S ZTDTH= “@” for th e second t ask—this c reates the task but does not s chedule it .
	10135	Output:zts k1^ztsk2:R eturns:
	10136	ztsk1^ztsk 2—If succe ssfully qu eued:
	10137	ztsk1 = ZT SK value o f first ta sk.
	10138	ztsk2 = ZT SK value o f second t ask.
	10139	-1—If unsu ccessful d evice call or failed %ZTLOAD c all.
	10140
	10141	Example
	10142	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so y ou divide the job in to two tas ks. The fi rst task g athers the informati on, and th e second t ask prints it. Use t he $$QQ^XU TMDEVQ API to select the devic e, schedul e the gath er task, a nd queue t he print t ask. Use t he $$REQQ^ XUTMDEVQ() : Schedule Second Pa rt of a Ta sk API to schedule t he print t ask when t he gather task finis hes.
	10143	NOTE: This is the ea siest way to divide a job into two tasks .
	10144	Figure 106 : $$QQ^XUT MDEVQ API— Sample cod e
	10145	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10146	; ;1.1
	10147	QQ ;
	10148	N X
	10149	S X=$$QQ^XU TMDEVQ(“GA THERQ^ARHB QQ”,“ARHB Gather”,,, ,,1,“PRINT Q^ARHBQQ”, “ARHB Prin t”)
	10150	W !,“X=”,X
	10151	Q
	10152	GATHERQ ;
	10153	N ARHJ,X
	10154	S ZTREQ=“@”
	10155	S ARHJ=“ARH B-QQ”_“-”_ $J_“-”_$H ; namespac e + unique ID
	10156	K ^XTMP(ARH J) ; Use ^ XTMP to pa ss a lot o f data bet ween tasks .
	10157	S ^XTMP(ARH J,0)=$$FMA DD^XLFDT(D T,1)_U_DT ; Save-thr u and crea te dates.
	10158	S ^XTMP(ARH J)=“HI MOM !” ; Prete nd this is a lot of data!
	10159	; XUTMQQ ho lds the ZT SK of the print task
	10160	S X=$$REQQ^ XUTMDEVQ(X UTMQQ,$H,“ ARHJ”) ; S chedule pr int task t o start
	10161	Q
	10162	PRINTQ ;
	10163	S ZTREQ=“@”
	10164	; U IO ; Don ’t need th is if invo ked using a ^XUTMDEV Q API.
	10165	W !,“The se cret messa ge is: ‘”, $G(^XTMP(A RHJ)),“‘”
	10166	K ^XTMP(ARH J)
	10167	Q
	10168
	10169	$$REQQ^XUT MDEVQ(): S chedule Se cond Part of a Task
	10170	Reference Type:Suppo rted
	10171	Category:T askMan
	10172	ICR #:1519
	10173	Descriptio n:This ext rinsic fun ction sche dules the second tas k (i.e., p rint data) from the $$QQ^XUTMD EVQ(): Dou ble Queue— Direct Que uing in a Single Cal l API. Thi s API was added with Kernel pa tch XU8.0 389.
	10174	If it take s a long t ime to gat her and pr int data, users shou ld split t he job int o two task s:
	10175	Gather Dat a—The firs t task gat hers the d ata.
	10176	Print Data —The secon d task pri nts the da ta.
	10177	Separating the data- gathering task from the data p rint task helps avoi d unnecess arily tyin g up a pri nter while large amo unts of da ta are gat hered.
	10178	This API m akes sure that only the schedu led time a nd any var iables in %VAR are p assed to t he REQ^%ZT LOAD: Requ eue a Task .
	10179	Format:$$R EQQ^XUTMDE VQ(xutsk,x udth[,[.]% var])
	10180	Input Para meters:xut sk:(requir ed) This i nput param eter is th e TaskMan task to sc hedule the second ta sk from th e $$QQ^XUT MDEVQ(): D ouble Queu e—Direct Q ueuing in a Single C all API an d should b e in the X UTMQQ vari able.
	10181	xudth:(req uired) Thi s input pa rameter is the new s cheduled r un time.
	10182	[.]%var:(o ptional) T his input parameter is convert ed to the ZTSAVE var iable; it is the sam e as the % var input parameter for the $$ DEV^XUTMDE VQ(): Forc e Queuing— Ask for De vice API.
	10183	Output:ret urns:Retur ns:
	10184	1—Successf ul.
	10185	0—Unsucces sful.
	10186
	10187	Example
	10188	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so y ou divide the job in to two tas ks. The fi rst task g athers the informati on, and th e second t ask prints it. Use t he $$QQ^XU TMDEVQ(): Double Que ue—Direct Queuing in a Single Call API t o select t he device, schedule the gather task, and queue the print tas k. Use the $$REQQ^XU TMDEVQ API to schedu le the pri nt task wh en the gat her task f inishes.
	10189	NOTE: This is the ea siest way to divide a job into two tasks .
	10190	Figure 107 : $$REQQ^X UTMDEVQ AP I—Sample c ode
	10191	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10192	; ;1.1
	10193	QQ ;
	10194	N X
	10195	S X=$$QQ^XU TMDEVQ(“GA THERQ^ARHB QQ”,“ARHB Gather”,,, ,,1,“PRINT Q^ARHBQQ”, “ARHB Prin t”)
	10196	W !,“X=”,X
	10197	Q
	10198	GATHERQ ;
	10199	N ARHJ,X
	10200	S ZTREQ=“@”
	10201	S ARHJ=“ARH B-QQ”_“-”_ $J_“-”_$H ; namespac e + unique ID
	10202	K ^XTMP(ARH J) ; Use ^ XTMP to pa ss a lot o f data bet ween tasks .
	10203	S ^XTMP(ARH J,0)=$$FMA DD^XLFDT(D T,1)_U_DT ; Save-thr u and crea te dates.
	10204	S ^XTMP(ARH J)=“HI MOM !” ; Prete nd this is a lot of data!
	10205	; XUTMQQ ho lds the ZT SK of the print task
	10206	S X=$$REQQ^ XUTMDEVQ(X UTMQQ,$H,” ARHJ”) ; S chedule pr int task t o start
	10207	Q
	10208	PRINTQ ;
	10209	S ZTREQ=“@”
	10210	; U IO ; Don ’t need th is if invo ked using a ^XUTMDEV Q API.
	10211	W !,“The se cret messa ge is: ‘”, $G(^XTMP(A RHJ)),“‘”
	10212	K ^XTMP(ARH J)
	10213	Q
	10214
	10215	DISP^XUTMO PT(): Disp lay Option Schedule
	10216	Reference Type:Suppo rted
	10217	Category:T askMan
	10218	ICR #:1472
	10219	Descriptio n:This API displays the schedu le for an option.
	10220	Format:DIS P^XUTMOPT( option_nam e)
	10221	Input Para meters:opt ion_name:( required) The name o f the opti on from th e OPTION f ile (#19) for which the TaskMa n schedule is to be displayed.
	10222	Output:ret urns:Retur ns the Tas kMan optio n schedule .
	10223
	10224	Example
	10225	>D DISP^XU TMOPT(opti on_name)
	10226
	10227	EDIT^XUTMO PT(): Edit an Option ’s Schedul ing
	10228	Reference Type:Suppo rted
	10229	Category:T askMan
	10230	ICR #:1472
	10231	Descriptio n:This API allows us ers to edi t an optio n’s schedu ling in th e OPTION S CHEDULING file (#19. 2).
	10232	Format:EDI T^XUTMOPT( option_nam e)
	10233	Input Para meters:opt ion_name:( required) The name o f the opti on from th e OPTION f ile (#19) whose sche dule the u ser is to be allowed to edit.
	10234	Output:ret urns:Retur ns the req uested opt ion in ord er to edit the sched ule.
	10235
	10236	OPTSTAT^XU TMOPT(): O btain Opti on Schedul e
	10237	Reference Type:Suppo rted
	10238	Category:T askMan
	10239	ICR #:1472
	10240	Descriptio n:This API allows an applicati on to find out when an option is schedul ed and get other dat a.
	10241	Format:OPT STAT^XUTMO PT(option_ name,.root )
	10242	Input Para meters:opt ion_name:( required) The name o f the opti on from th e OPTION f ile (#19) upon which to return data.
	10243	.root:(req uired) Thi s variable is passed by refere nce. This is an arra y because the same t ask can be scheduled more than once.
	10244	Output:.ro ot:Returns an array of data ab out the op tion in qu estion.
	10245
	10246	Example
	10247	>D OPTSTAT ^XUTMOPT(“ OPTION NAM E”,.ROOT)
	10248
	10249	Returns an array of data in RO OT (pass b y ref) in the form:
	10250	ROOT=count ROOT(1)=t ask number ^scheduled time^resc hedule fre q^special queuing fl ag
	10251
	10252	RESCH^XUTM OPT(): Set Up Option Schedule
	10253	Reference Type:Suppo rted
	10254	Category:T askMan
	10255	ICR #:1472
	10256	Descriptio n:This API allows an applicati on to set up the sch edule for an option.
	10257	Format:RES CH^XUTMOPT (option_na me[,when_t o_run][,de vice_to_us e][,resche dule_freq] [,flags][, .error_arr ay])
	10258	Input Para meters:opt ion_name:( required) The name o f the opti on from th e OPTION f ile (#19) to be resc heduled.
	10259	when_to_ru n:(optiona l) The new scheduled time for the option to run.
	10260	device_to_ use:(optio nal) The d evice to u se for the reschedul ed option.
	10261	reschedule _freq:(opt ional) The frequency to run th e reschedu led option .
	10262	flags:(opt ional) If the flag i s set to a n “L” LAYG O a new en try if nee ded.
	10263	.error_arr ay:(option al) Passed by refere nce.
	10264	Output Par ameters:.e rror_array :(optional ) This is set to -1 if the opt ion was no t found.
	10265
	10266	EN^XUTMTP( ): Display HL7 Task Informatio n
	10267	Reference Type:Contr olled Subs cription
	10268	Category:T askMan
	10269	ICR #:3521
	10270	Descriptio n:This API is displa ys the Hea lth Level Seven (HL7 )-related task infor mation. Fi rst, the c urrently r unning tas ks are exa mined in t he SCHEDUL E file. Fo r each tas k found, e xamine the ROUTINE f ield. If t he ROUTINE field con tains “HL” , it is a Health Lev el Seven-r elated tas k.
	10271	Format:EN^ XUTMTP(tas k[,ztenv,z tkey,ztnam e,ztflag,x utmuci])
	10272	Input Para meters:tas k:(require d) TaskMan ’s task ID .
	10273	ztenv:(opt ional) Set = 1.
	10274	ztkey:(opt ional) Set = 0.
	10275	ztname:(op tional) Se t = ,User name.
	10276	ztflag:(op tional) Se t = 1.
	10277	xutmuci:(o ptional) X ^%ZOSF(“U CI”) S XUT MUCI=Y
	10278	Output:ret urns:Retur ns the HL7 -related t ask inform ation. The following is an exa mple of th e informat ion displa yed by thi s API:
	10279	261181: EN ^HLCSLM, H L7 Link Ma nager. No device. DE V,MOU.From 12/31/200 1 at 14:17 , By XUUS ER,THIRTY. Started ru nning 12/3 1/2001 at 14:17. Jo b #: 56203 9155
	10280
	10281	^%ZTLOAD: Queue a Ta sk
	10282	^%ZTLOAD i s the main API used to create and schedu le tasks ( commonly r eferred to as “queui ng”). Queu ing tells TaskMan to use a bac kground pa rtition to DO a cert ain API at a certain time, wit h certain other cond itions est ablished a s describe d by the i nput varia bles.
	10283	Reference Type:Suppo rted
	10284	Category:T askMan
	10285	ICR #:1006 3
	10286	Descriptio n:This API , as used in code, b ehaves con sistently so most qu euers stro ngly resem ble one an other. The queuer ca n be writt en so that it is eit her intera ctive with the user or so that it is not interacti ve. The st andard var iations on this stru cture dese rve attent ion.
	10287	Format:^%Z TLOAD
	10288	Make sure to perform the follo wing steps before ca lling this API:
	10289	NEW all no n-namespac ed variabl es.
	10290	Set all in put variab les.
	10291	Call the A PI.
	10292	Input Vari able:ZTRTN :(required ) The API that TaskM an will DO to start the task. You can sp ecify it a s “LABEL^R OUTINE” or “^ROUTINE ” or “ROUT INE”. If i t is not p assed, the original API is use d.
	10293	ZTDESC:(re quired) Ta sk descrip tion, up t o 200 char acters des cribing th e task, wi th the sof tware appl ication na me at the front. Whi le not req uired, use of this v ariable is recommend ed.
	10294	ZTDTH:(opt ional) Sta rt Time wh en TaskMan should st art the ta sk. It mus t be a dat e and time in VA Fil eMan or $H OROLOG for mat. Setti ng it to “ @”causes t he task to be create d but not scheduled. If ZTDTH is not set , ^%ZTLOAD asks the user for t he start t ime.
	10295	ZTIO:(opti onal) The I/O device the task should use . If ZTIO is NULL, n o device i s used. If undefined , the curr ent I/O va riables ar e used to select a d evice. ZTI O should o nly be use d when the current I /O variabl es do not describe t he needed device. If you do no t need a d evice for a job, SET ZTIO=“”. The ZTIO v ariable ac cepts the same I/O f ormatting string as the IOP va riable in the
	10296	^%ZIS: Sta ndard Devi ce Call.
	10297	REF: For m ore inform ation, see the “Devi ce Handler : Develope r Tools” s ection.
	10298	ZTUCI:(opt ional) UCI the task should use . The curr ent UCI is used if Z TUCI is un defined.
	10299	ZTCPU:(opt ional) Vol ume Set:CP U. Specifi es the nam e of the v olume set and CPU on which the task shou ld run. Th e volume s et can be passed in the first :-piece, a nd the CPU in the se cond. Neit her piece of informa tion is re quired; ei ther can b e passed w ithout the other. If the CPU a lone is pa ssed, it m ust still be precede d by a “:” (e.g., :K DAISC6A1). If the vo lume set i s not pass ed, TaskMa n runs the task on t he volume set it cam e from or on a Print Server. I f the CPU is not pas sed, TaskM an runs th e task on the CPU wh ere TaskMa n resides. Any volum e set and/ or CPU spe cified by the task’s I/O devic e takes pr ecedence o ver the sa me informa tion passe d here.
	10300	NOTE: On C aché syste ms, specif ying which CPU a job should ru n on only works if y ou are run ning TaskM an from a DCL contex t. If you specify th e CPU, but are not r unning Tas kMan from a DCL cont ext, the j ob may not run corre ctly.
	10301	ZTPRI:(opt ional) The CPU prior ity the ta sk should receive. I t should b e an integ er between 1 (low) a nd 10 (hig h). The si te’s defau lt for tas ks is used if this i s undefine d.
	10302	ZTSAVE():( optional) Input vari able array . An array whose nod es specify input var iables to the task b eyond the usual set all tasks receive. T here are f our kinds of nodes t his array can have:
	10303	ztsave(“va riable”) c an be set equal to N ULL or to a value; i f NULL, th e current value of t hat variab le is copi ed for the task, oth erwise the variable is created with the value assi gned [for example, z tsave(“PSI N”)=42]. T he variabl e can be l ocal or gl obal, and it can be a variable or an ind ividual ar ray node.
	10304	ZTSAVE(“op en array r eference”) can be se t to NULL to declare a set of nodes with in an arra y to be in put variab les to the task [for example, ZTSAVE(“^U TILITY($J, ”)].
	10305	ZTSAVE(“na mespace”) can be se t to NULL to save al l local va riables in a certain namespace [for exam ple, ZTSAV E(“LR”)].
	10306	ZTSAVE(“*” ) can be u sed to sav e all loca l variable s. Non-nam espaced va riables (e sp. %, X, Y, etc.) m ay or may not be sav ed. Saving individua l variable s is more efficient. ZTSAVE no des are sa ved just a s they are typed, so special v ariables l ike $J hav e one valu e when use d to save the variab les, and a different value whe n used to restore th em for the task.
	10307	ZTKIL:(opt ional) KEE P UNTIL. S et this to the first day the T ask File C leanup can delete th is task. I t should b e a date a nd time in VA FileMa n or $HORO LOG format . Use of t his variab le is reco mmended wh en ZTDTH e quals “@”.
	10308	ZTSYNC:(op tional) Na me of a SY NC FLAG. U sing SYNC FLAGS allo ws TaskMan to run th e next tas k in a ser ies of tas ks only if the prece ding task in the ser ies comple ted succes sfully.
	10309	You can ch oose any n ame for a SYNC FLAG. You shoul d namespac e the name , however, and make it no long er than 30 character s in lengt h.
	10310	To use SYN C FLAGs, t he task mu st be queu ed to a de vice of ty pe resourc e (through the ZTIO variable).
	10311	REF: For c omplete in formation on how to use SYNC F LAGs, see the “Using SYNC FLAG s to Contr ol Sequenc es of Task s” section in this s ection.
	10312
	10313	Output Var iables:ZTS K:(Usually returned) The task number ass igned to a task, ret urned when ever a tas k is succe ssfully cr eated. It can be use d as an in put variab le to the other Task Man applic ation mode APIs.
	10314	NOTE: If a task is q ueued to a volume se t other th an the one where it was create d, it is u sually ass igned a ne w task num ber when i t is moved .
	10315	If ztsk is not defin ed after c alling ^%Z TLOAD, eit her ztrtn was not se t up or th e user can celed the creation w hen prompt ed for a s tart time. If a task is not cr eated and if ^%ZTLOA D is being called by a foregro und job, t hen ^%ZTLO AD display s a messag e to the u ser indica ting that the task h as been ca nceled.
	10316	NOTE: ZTSK is not a system var iable. It is KILLed and manipu lated in m any places . If the s oftware ne eds to rem ember a ta sk number, ztsk shou ld be set into some properly n amespaced variable t he applica tion can p rotect.
	10317	ZTSK(“D”): START TIME (usually returned) contains t he task’s requested start time in $HOROL OG format. It is ret urned when ever ztsk is returne d, and giv es you a w ay to know the start time a us er request s.
	10318
	10319	Interactiv e Use of ^ %ZTLOAD
	10320	The VistA Standards and Conven tions requ ire that a nywhere yo u let a us er pick th e output d evice you also let t he user ch oose to qu eue the ou tput.
	10321	Often one part of th e queuer i s a call t o ^%ZIS (t he Device Handler). When you s et up the variables for your c all, inclu de a “Q” i n the vari able ^%ZIS so the De vice Handl er lets th e user pic k queuing. After the Device Ha ndler call (and afte r you chec k POP to e nsure that a valid d evice was selected), you can c heck $DATA (IO(“Q”)) to see whe ther the u ser chose to queue t o that dev ice. If so , then you must queu e the prin tout you w ere about to do dire ctly, and your softw are should branch to the code to set up the task. A sample o f the code for this kind of pr int queuer looks som ething lik e this:
	10322	Figure 108 : ^%ZTLOAD API—Print queuer sa mple code
	10323	SELECT ;select IO device for report
	10324	S %ZIS=“ Q” D ^%ZIS
	10325	I POP D CANCEL Q
	10326	I $D(IO( “Q”)) D QU EUE Q
	10327	D PRINT, ^%ZISC Q
	10328	;
	10329	QUEUE ;queue th e report
	10330	S ZTRTN= “PRINT^ZZR EPORT”
	10331	S ZTDESC =“ZZ Appli cation Dai ly Report 1”
	10332	S ZTSAVE (“ZZRANGE” )=“”
	10333	D ^%ZTLO AD
	10334	I $D(ZTS K)[0 W !!? 5,“Report canceled!”
	10335	E W !!? 5,“Report queued!”
	10336	D HOME^% ZIS Q
	10337
	10338	The code t o set up t he task af ter the ca ll to ^%ZI S has four steps. Fi rst, it se ts the ^%Z TLOAD inpu t variable s to defin e the task . Second, it calls ^ %ZTLOAD to queue the task. Thi rd, it che cks $DATA( ZTSK)#2 to find out whether a task was r eally queu ed and pro vides appr opriate fe edback. Fo urth, it c alls HOME^ %ZIS to re set its IO variables .
	10339	NOTE: This queuer di d not defi ne the ZTI O variable . Print qu euers can take advan tage of th e fact tha t they dir ectly foll ow a ^%ZIS call that sets up a ll the IO variables they need. Under the se conditi ons, the q ueuer code can rely on ^%ZTLOA D to ident ify the ta sk’s IO de vice from the IO var iables, th us, saving the devel oper the w ork of bui lding the correct ZT IO string.
	10340	Notice als o that whe n queuing output, we need not call ^%ZIS C to close the IO de vice becau se when th e user cho oses to qu eue output the Devic e Handler does not o pen the de vice. Thus , all we n eed to do here is re set our IO variables with a HO ME^%ZIS ca ll.
	10341	As usual i n these ki nds of que uers, we d id not def ine ZTDTH, but inste ad let ^%Z TLOAD ask the user w hen the re port shoul d run.
	10342	Finally, n otice that we tell t he task to begin at PRINT, the same tag used by th e trigger code to st art the fo reground p rint when the user c hooses not to queue. Under mos t circumst ances, pri nt queuers can use m ost of the same code for their tasks tha t the fore ground pri nt uses.
	10343	Non-intera ctive Use of ^%ZTLOA D
	10344	Under cert ain condit ions, queu ers must c reate and schedule t heir tasks with no i nteraction with the user. Exam ples inclu de queuers operating out of ta sks or que uers that need to ru n without the users’ knowledge . Only two items mus t be chang ed from in teractive queuers to make non- interactiv e queuers work:
	10345	ZTDTH must be passed to ^%ZTLO AD, and mu st contain a valid d ate/time v alue.
	10346	If the cod e to queue the task does not f ollow a ca ll to ^%ZI S, you mus t define t he ZTIO va riable you rself. Eit her set it , or allow it to be built from the curre nt I/O var iables (if those I/O variables describe the proper device).
	10347	After the call to ^% ZTLOAD, yo u may (or may not) w ant to iss ue feedbac k messages .
	10348	Queuing Ta sks withou t an I/O D evice
	10349	Certain ta sks need n o IO devic e. These i nclude pri marily tas ks that re arrange la rge amount s of data but produc e no repor t, such as filing an d compilin g tasks. T wo differe nt kinds o f non-IO t asks exist :
	10350	Concurrent —Those tha t can run concurrent ly.
	10351	Sequential —Those tha t must run sequentia lly.
	10352	Queuers fo r concurre nt non-IO tasks need only set ZTIO to NU LL, and Ta skMan runs the task, with no I O device.
	10353	For sequen tial non-I O tasks, q ueuers mus t set the ZTIO varia ble to the name of a resource type devic e. TaskMan then ensu res that t he tasks r un single file, one after the other in o rder by re quested st art time. Applicatio ns that ne ed sequent ial non-IO tasks sho uld instru ct system managers i n the Pack age Instal lation Gui de to crea te a resou rce device with the desired ch aracterist ics so tha t these qu euers can safely que ue their t asks to th em. Such d evices sho uld be nam espaced by the softw are applic ation that uses them . SYNC FLA Gs can als o be used to allow t he next ta sk in a se ries to st art only i f the prev ious task in the ser ies comple ted succes sfully.
	10354	REF: For m ore inform ation on S YNC FLAGs, see the “ Using SYNC FLAGs to Control Se quences of Tasks” se ction in t his sectio n.
	10355	Example
	10356	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so y ou divide the job in to two tas ks. The fi rst task g athers the informati on and the second ta sk prints it. Use th e ^%ZIS: S tandard De vice Call API to sel ect the de vice, the ^%ZTLOAD A PI to queu e the prin t task, an d the ^%ZT LOAD API t o schedule the gathe r task. Us e the REQ^ %ZTLOAD: R equeue a T ask API to schedule the print task when the gather task fini shes.
	10357	NOTE: This process i s made eas ier by usi ng the $$Q Q^XUTMDEVQ (): Double Queue—Dir ect Queuin g in a Sin gle Call a nd $$REQQ^ XUTMDEVQ() : Schedule Second Pa rt of a Ta sk APIs.
	10358	Figure 109 : ^%ZTLOAD API—Sampl e code
	10359	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10360	; ;1.1
	10361	ZTLOAD ;
	10362	N ARH,ARHZT SK,X,ZTSAV E,%ZIS,ZTS K,ZTDTH,ZT RTN,ZTDESC ,ZTIO,POP
	10363	W !,“Queue the second task (the print tas k) first.” ,!
	10364	; Let’s deal with the second tas k first.
	10365	; The user d oesn’t kno w it, but he’s actua lly queuin g the seco nd task,
	10366	; the “print ” portion of the job . The onl y question the user will be
	10367	; asked is t o select t he device.
	10368	;
	10369	S %ZIS=“QM”
	10370	S IOP=“Q” ; Force queu ing.
	10371	D ^%ZIS Q:P OP ; Sele ct Device
	10372	W !,“Finish ed with %Z IS.”
	10373	;
	10374	S ZTDTH=“@” ;Don’t sc hedule the task to r un, we’ll do it late r
	10375	; If we didn ’t need to set ZTDTH , we could use EN^XU TMDEVQ, bu t that
	10376	; I ‘new’s Z TDTH, so w e can’t se t it.
	10377	;
	10378	; BTW, Did y ou know th at there’s a 5th par ameter in EN^XUTMDEV Q?
	10379	; Usually, E N^XUTMDEVQ will ‘new ’ ZTSK, so you can’t get to it .
	10380	; If you put “1” as th e 5th para meter, ZTS K will exi st when EN returns.
	10381	; D EN^XUTMD EVQ(“PRINT ^ARHBQQ”,“ ARHB Print ”,.ZTSAVE, .%ZIS,1)
	10382	;
	10383	S ZTRTN=“PR INT^ARHBQQ ”
	10384	S ZTDESC=“A RHB Print”
	10385	D ^%ZTLOAD
	10386	D HOME^%ZIS
	10387	W !,“ZTSK=” ,$G(ZTSK)
	10388	Q :’$D(ZTSK)
	10389	S ARHZTSK=Z TSK
	10390	;
	10391	N ZTSAVE,%Z IS,ZTSK,ZT DTH,ZTRTN, ZTDESC,ZTI O,IOP
	10392	W !,“Now qu eue the fi rst task ( the gather task).”,!
	10393	; Now queue the first task, the “gather” p ortion of the job.
	10394	; Since we d on’t need a device,
	10395	; the user w ill only b e asked wh en to star t the task .
	10396	; (I wasn’t able to ge t EN^XUTMD EVQ to wor k for me. I tried s etting
	10397	; IOP=“Q;” t o let it k now that i t should b e queued a nd it didn ’t need
	10398	; a device, but it did nothing, and return ed a null ZTSK.)
	10399	F I=“ARHZTS K” S ZTSAV E(I)=“” ; Save the Z TSK of the “print” t ask.
	10400	S ZTIO=“” ; We don’t need a dev ice.
	10401	S IOP=“Q” ; Force que uing.
	10402	S ZTRTN=“GA THER^ARHBQ Q”
	10403	S ZTDESC=“A RHB Gather ”
	10404	D ^%ZTLOAD
	10405	D HOME^%ZIS
	10406	W !,“ZTSK=” ,$G(ZTSK)
	10407	Q
	10408	GATHER ;
	10409	N ARHJ
	10410	S ZTREQ=“@”
	10411	S ARHJ=“ARH B-QQ”_”-”_ $J_”-”_$H ; namespac e + unique ID
	10412	K ^XTMP(ARH J) ; Use ^ XTMP to pa ss a lot o f data bet ween tasks .
	10413	S ^XTMP(ARH J,0)=$$FMA DD^XLFDT(D T,1)_U_DT ; Save-thr u and crea te dates.
	10414	S ^XTMP(ARH J)=“HI MOM !” ; Prete nd this is a lot of data.
	10415	D SPRINT
	10416	Q
	10417	SPRINT ; Now sched ule the “p rint” task to run.
	10418	N ZTSK,ZTDT H,I,ZTRTN, ZTDESC,ZTI O,ZTSAVE ; Very impo rtant to N EW the
	10419	; input var iables to REQ^%ZTLOA D, otherwi se they re tain the v alues of
	10420	; the curre ntly runni ng task, a nd you cou ld uninten tionally c hange the
	10421	; “print” t ask to rer un the “ga ther” task .
	10422	F I=“ARHJ” S ZTSAVE(I )=“” ; Let the “prin t” task kn ow the “$J ” value.
	10423	S ZTSK=ARHZ TSK
	10424	S ZTDTH=$H
	10425	D REQ^%ZTLO AD
	10426	; Instead of the above 8 lines w e could ha ve simply:
	10427	; S X=$$REQQ ^XUTMDEVQ( ARHZTSK,$H ,“ARHJ”)
	10428	Q
	10429	PRINT ;
	10430	S ZTREQ=“@”
	10431	U IO ; Don’ t need thi s if invok ed using a ^XUTMDEVQ API.
	10432	W !,“The se cret messa ge is: ‘”, $G(^XTMP(A RHJ)),“‘”
	10433	K ^XTMP(ARH J)
	10434	Q
	10435
	10436	Code Execu tion
	10437	Figure 110 : ^%ZTLOAD API—Sampl e code exe cution
	10438	VAH>D ZTLO AD^ARHBQQ
	10439
	10440	Queue the second tas k (the pri nt task) f irst.
	10441	QUEUE TO P RINT ON
	10442	DEVICE: HO ME// P-MES S
	10443
	10444	1 P-MESSA GE-ENGWO-H FS-VXD H FS FILE == > MAILMESS AGE
	10445	2 P-MESSA GE-HFS-VXD HFS FIL E ==> MAIL MESSAGE
	10446	Choose 1-2 > 2 <Enter > P-MESSA GE-HFS-VXD HFS FILE ==> MAILM ESSAGE
	10447
	10448	Subject: M Y PRINT
	10449
	10450	Selec t one of t he followi ng:
	10451
	10452	M Me
	10453	P Postmaster
	10454
	10455	From whom: Postmaste r// <Enter >
	10456	Send mail to: XUUSER ,ONE// <En ter> XUUS ER,ONE
	10457	Select bas ket to sen d to: IN// <Enter>
	10458	And Send t o: <Enter>
	10459	Finished w ith %ZIS.
	10460	ZTSK=29214 97
	10461	Now queue the first task (the gather tas k).
	10462
	10463	Requested Start Time : NOW// <E nter> (JA N 25, 2005 @11:30:35)
	10464	ZTSK=29214 99
	10465
	10466	Output
	10467	Figure 111 : ^%ZTLOAD API—Sampl e output
	10468	Subj: MY P RINT [#28 881111] 01 /25/05@11: 30 2 line s
	10469	From: POST MASTER (Se nder: XUUS ER,ONE - C OMPUTER SP ECIALIST) In ‘IN’
	10470	basket.
	10471	Page 1 N ew
	10472	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	10473
	10474	The secret message i s: ‘HI MOM !’
	10475
	10476	Enter mess age action (in IN ba sket): Ign ore//
	10477
	10478	$$ASKSTOP^ %ZTLOAD: S top TaskMa n Task
	10479	Reference Type:Suppo rted
	10480	Category:T askMan
	10481	ICR #:1006 3
	10482	Descriptio n:This ext rinsic fun ction asks TaskMan t o stop run ning a spe cified tas k. Also, i t checks f or the ZTN AME variab le, and if defined, it uses it instead o f DUZ to v alue the S TOP FLAG f ield (#59. 1). ZTNAME is suppor ted by app lications calling th is API to indicate t he process that aske d the task to stop.
	10483	Format:$$A SKSTOP^%ZT LOAD(ztsk)
	10484	Input Para meters:zts k:(require d) Task nu mber of th e TaskMan task to be stopped.
	10485	Output:ret urns:Retur ns:
	10486	0—“Busy”. If it retu rns “Busy” , it could mean that the task is locked, someone e lse is cha nging it, or TaskMan is starti ng to run it.
	10487	1—“Task mi ssing” or Task “Fini shed runni ng”. If it returns “ Task missi ng”, it co uld mean t hat it was an incorr ect input task numbe r, but it is most li kely that the task r an and was removed a fter runni ng.If it r eturns “Fi nished run ning”, it means that the task was finish ed running before th e API requ est could go through , so the A PI could n ot stop an already f inished ta sk.
	10488	2—“Asked t o stop” or “Unschedu led”. If i t returns “Asked to Stop”, the task has started ru nning and the stop f lag has be en set, so if the ap plication checks ($$ S^%ZTLOAD) it should stop.If i t returns “Unschedul ed”, it wa s successf ul and the task is n ot schedul ed any mor e.
	10489
	10490	DESC^%ZTLO AD(): Find Tasks wit h a Descri ption
	10491	Reference Type:Suppo rted
	10492	Category:T askMan
	10493	ICR #:1006 3
	10494	Descriptio n:This API finds tas ks with a specific d escription .
	10495	Format:DES C^%ZTLOAD( descriptio n,list)
	10496	Input Para meters:des cription:( required) The TaskMa n task des cription.
	10497	Output Par ameters:li st:Returns a list of tasks wit h the spec ified desc ription.
	10498
	10499	DQ^%ZTLOAD : Unschedu le a Task
	10500	Reference Type:Suppo rted
	10501	Category:T askMan
	10502	ICR #:1006 3
	10503	Descriptio n:This API unschedul es tasks. Unscheduli ng a task ensures th at, after the call, it is not scheduled or waiting for a dev ice, compu ter link, or partiti on in memo ry. Unsche duling is guaranteed to be suc cessful as long as t he task is currently defined i n the TASK S file (#1 4.4). Howe ver, unsch eduling a task that has alread y started running do es not sto p the task in any wa y.
	10504	Format:DQ^ %ZTLOAD
	10505	Make sure to perform the follo wing steps before ca lling this API:
	10506	NEW all no n-namespac ed variabl es.
	10507	Set all in put variab les.
	10508	Call the A PI.
	10509	Input Vari ables:ZTSK :(required ) The numb er of the task to un schedule. This task must curre ntly be de fined in t he TASKS f ile (#14.4 ) or the c all fails.
	10510	Output Var iables:ZTS K(0):Retur ns:
	10511	1—Task was unschedul ed success fully.
	10512	0—Task was not unsch eduled suc cessfully.
	10513
	10514	ISQED^%ZTL OAD: Retur n Task Sta tus
	10515	Reference Type:Suppo rted
	10516	Category:T askMan
	10517	ICR #:1006 3
	10518	Descriptio n:This API returns w hether a t ask is cur rently pen ding. Pend ing means that the t ask is sch eduled, wa iting for an I/O dev ice, waiti ng for a v olume set link, or w aiting for a partiti on in memo ry. It als o returns the DUZ of the task’ s creator and the ti me the tas k was sche duled to s tart.
	10519	Format:ISQ ED^%ZTLOAD
	10520	Make sure to perform the follo wing steps before ca lling this API:
	10521	NEW all no n-namespac ed variabl es.
	10522	Set all in put variab les.
	10523	Call the A PI.
	10524	Input Vari ables:ZTSK :(required ) Task num ber of the task to l ook up. Th e task mus t be curre ntly defin ed on the volume set to be sea rched, or the lookup fails.
	10525	ZTCPU:(opt ional) The volume se t TaskMan should sea rch for th e task bei ng looked up. If not passed, T askMan sea rches the current vo lume set. Unlike ^%Z TLOAD’s ZT CPU input variable, this one d oes not ac cept a sec ond :-piec e specifyi ng the CPU . It only specifies a volume s et to sear ch.
	10526	Output Var iables:ZTS K(0):ZTSK( 0) is retu rned as fo llows:
	10527	1—Task ZTS K is curre ntly sched uled or wa iting on v olume set ZTCPU.
	10528	0—Task ZTS K is not c urrently s cheduled o r waiting on volume set ZTCPU.
	10529	NULL (“”)— The lookup was unsuc cessful.
	10530	ZTSK(“E”): (sometimes returned) The error code, ret urned when some erro r conditio n prevente d a succes sful looku p. The cod es and the ir values are:
	10531	IT—The tas k number w as not val id (0, neg ative, or non-numeri c).
	10532	I—The task does not exist on t he specifi ed volume set.
	10533	IS—The vol ume set is not liste d in the V OLUME SET file (#14. 5).
	10534	LS—The lin k to that volume set is not av ailable.
	10535	U—An unexp ected erro r arose (e .g., disk full, prot ection, et c.).
	10536	ZTSK(“D”): (sometimes returned) The date and time t he task wa s schedule d to start , in $HORO LOG format . It is re turned onl y if ZTSK( 0) equals zero (0) o r 1.
	10537	ZTSK(“DUZ” ):(sometim es returne d) Holds t he DUZ of the user w ho created the task. It is ret urned only if ZTSK(0 ) equals z ero (0) or 1.
	10538
	10539	$$JOB^%ZTL OAD(): Ret urn a Job Number for a Task
	10540	Reference Type:Suppo rted
	10541	Category:T askMan
	10542	ICR #:1006 3
	10543	Descriptio n:This ext rinsic fun ction was released w ith Kernel patch XU* 8.0*339. I t returns the job nu mber for a running T askMan tas k.
	10544	Format:JOB ^%ZTLOAD(z tsk)
	10545	Input Para meters:zts k:(require d) Task nu mber of th e running TaskMan ta sk. If the specified task is n ot running , it retur ns null.
	10546	Output:ret urns:Retur ns the job number fo r the spec ified runn ing TaskMa n task.
	10547
	10548	KILL^%ZTLO AD: Delete a Task
	10549	Reference Type:Suppo rted
	10550	Category:T askMan
	10551	ICR #:1006 3
	10552	Descriptio n:This API deletes a task. Whe n a task i s deleted by KILL^%Z TLOAD, the task refe renced by ZTSK is no t defined in the vol ume set’s task file. If the ta sk was pen ding, it d oes not st art, but i f it had a lready sta rted runni ng, the ef fects of d eleting it s record a re unpredi ctable.
	10553	NOTE: Task s can dele te their o wn records through t he use of the ZTREQ output var iable.
	10554	Format:KIL L^%ZTLOAD
	10555	Make sure to perform the follo wing steps before ca lling this API:
	10556	NEW all no n-namespac ed variabl es.
	10557	Set all in put variab les.
	10558	Call the A PI.
	10559	Input Vari ables:ZTSK :(required ) Task num ber of the TaskMan t ask to del ete.
	10560	Output Var iables:ZTS K(0):Retur ns:
	10561	1—Successf ul deletio n of the t ask.
	10562	0—Requeste d task num ber is inv alid.
	10563
	10564	OPTION^%ZT LOAD(): Fi nd Tasks f or an Opti on
	10565	Reference Type:Suppo rted
	10566	Category:T askMan
	10567	ICR #:1006 3
	10568	Descriptio n:This API finds Tas kMan tasks for a spe cific opti on.
	10569	Format:OPT ION^%ZTLOA D(option,l ist)
	10570	Input Para meters:opt ion:(requi red) The n ame of the specific option.
	10571	Output Par ameters:li st:Returns a list of TaskMan t asks for t he specifi ed option.
	10572
	10573	PCLEAR^%ZT LOAD(): Cl ear Persis tent Flag for a Task
	10574	Reference Type:Suppo rted
	10575	Category:T askMan
	10576	ICR #:1006 3
	10577	Descriptio n:This API clears th e persiste nt flag fo r a TaskMa n task (cl ears the p ersistent node).
	10578	Format:PCL EAR^%ZTLOA D(ztsk)
	10579	Input Para meters:zts k:(require d) The Tas kMan task number.
	10580	Output:non e.
	10581
	10582	$$PSET^%ZT LOAD(): Se t Task as Persistent
	10583	Reference Type:Suppo rted
	10584	Category:T askMan
	10585	ICR #:1006 3
	10586	Descriptio n:This ext rinsic fun ction sets a TaskMan task as p ersistent (sets the persistent node). A task that is marked as persist ent is res tarted if TaskMan fi nds that t he lock on ^%ZTSCH(“ TASK”,task number) ha s been rem oved. This adds the requiremen t that the task only use incre mental loc ks, that t he entry i n ^%ZTSK(t ask... be left in pl ace as thi s restarts the task, and that the task c an be rest arted from the data that is in the ^%ZTS K(task,... global.
	10587	Format:$$P SET^%ZTLOA D(ztsk)
	10588	Input Para meters:zts k:(require d) The Tas kMan task number.
	10589	Output:ret urns:Retur ns:
	10590	1—Flag was set.
	10591	0—Flag was not set.
	10592
	10593	REQ^%ZTLOA D: Requeue a Task
	10594	Reference Type:Suppo rted
	10595	Category:T askMan
	10596	ICR #:1006 3
	10597	Descriptio n:This API unschedul es, edits, and resch edules a t ask. Unsch eduling en sures the task is no t pending but does n ot stop it from runn ing. Editi ng is limi ted to the API, star t time, de scription, and I/O d evice. Res cheduling is optiona l. However , if the t ask is not reschedul ed, it is vulnerable to the Ta sk File Cl eanup opti on. The en tire proce dure is re ferred to as requeui ng.
	10598	CAUTION: B ecause req ueuing doe s not invo lve stoppi ng a runni ng task, i t is possi ble to win d up with the same t ask runnin g in two d ifferent p artitions if the alg orithm is not design ed careful ly. This i s not supp orted by T askMan; th us, develo pers shoul d use requ euing very carefully . Queuing a new task is usuall y a better way to ac complish t he same go als.
	10599	NOTE: Task s can resc hedule the mselves th rough use of the ZTR EQ output variable.
	10600	Format:REQ ^%ZTLOAD
	10601	Make sure to perform the follo wing steps before ca lling this API:
	10602	NEW all no n-namespac ed variabl es.
	10603	Set all in put variab les.
	10604	Call the A PI.
	10605	Input Vari ables:ZTSK :(required ) The Task Man task n umber of t he task to edit. It must be de fined on t he current volume se t for the edit to su cceed. It is strongl y recommen ded that t his task n ot be curr ently runn ing.
	10606	ZTDESC:(op tional) Ne w descript ion for th e task. It should de scribe the task and name the s oftware ap plication that creat ed the tas k.
	10607	ZTDTH:(opt ional) New start tim e for the task. Pass this as a date and time in VA FileMan o r $HOROLOG format. I f not pass ed, the or iginal sta rt time is used agai n. If pass ed as “@”, the task is not res cheduled.
	10608	The ZTDTH input vari able can a lso be pas sed as a r eschedulin g code. Th is code is a number followed b y an “S” ( seconds), an “H” (ho urs), or a “D” (days ). This co de represe nts an int erval of t ime (e.g., “60S” is 60 seconds ) that is added to t he current time (for seconds o r hours) o r the orig inal start time (for days) to produce th e new star t time.
	10609	ZTIO:(opti onal) New I/O device for the t ask. It se ts IOP in the ^%ZIS: Standard Device Cal l API, and can take all of IOP ’s format specificat ion string s. If the ZTIO varia ble is set to “@”, t he task is reschedul ed for no I/O device . If the Z TIO variab le is set to NULL or it is not passed, t he origina lly reques ted I/O de vice is us ed.
	10610	ZTIO(“H”)— If not set , it is se t to the v alue of th e IO("HFSI O") variab le in the ^%ZIS: Sta ndard Devi ce Call AP I.
	10611	ZTIO(“P”)— If not set , it is se t to the v alue of th e IOPAR va riable in the ^%ZIS: Standard Device Cal l API.
	10612	ZTRTN:(opt ional) The API TaskM an will DO to start the task. You can sp ecify it a s “LABEL^R OUTINE” or “^ROUTINE ” or “ROUT INE”. If i t is not p assed, the original API is use d.
	10613	ZTSAVE:(op tional) In put variab le array. An array w hose nodes specify i nput varia bles to th e task bey ond the us ual set al l tasks re ceive. It is set up in the sam e format a s the ZTSA VE input v ariable fo r the ^%ZT LOAD API.
	10614	Output Var iables:ZTS K(0):Retur ns:
	10615	1—Task is defined.
	10616	0—Task is not define d or ZTDTH was passe d in a bad format.
	10617
	10618	Example
	10619	This examp le is a jo b that con sists of g athering i nformation and then printing i t. Assume that the g athering t akes a few hours. Yo u do not w ant the de vice that the user s elects to be tied up for that time, so d ivide the job into t wo tasks. The first task gathe rs the inf ormation a nd the sec ond task p rints it. Use the ^% ZIS: Stand ard Device Call API to select the device , the ^%ZT LOAD: Queu e a Task A PI to queu e the prin t task and schedule the gather task. Use the REQ^% ZTLOAD API to schedu le the pri nt task wh en the gat her task f inishes.
	10620	NOTE: This process i s made eas ier by usi ng the $$Q Q^XUTMDEVQ (): Double Queue—Dir ect Queuin g in a Sin gle Call a nd $$REQQ^ XUTMDEVQ() : Schedule Second Pa rt of a Ta sk APIs.
	10621	Figure 112 : REQ^%ZTL OAD API—Sa mple code
	10622	ARHBQQ ; SFVAMC/GB - Demo of ‘gather’ a nd ‘print’ in 2 task s ;1/19/06 08:31
	10623	; ;1.1
	10624	ZTLOAD ;
	10625	N ARH,ARHZT SK,X,ZTSAV E,%ZIS,ZTS K,ZTDTH,ZT RTN,ZTDESC ,ZTIO,POP
	10626	W !,“Queue the second task (the print tas k) first.” ,!
	10627	; Let’s deal with the second tas k first.
	10628	; The user d oesn’t kno w it, but he’s actua lly queuin g the seco nd task,
	10629	; the “print ” portion of the job . The onl y question the user will be
	10630	; asked is t o select t he device.
	10631	;
	10632	S %ZIS=“QM”
	10633	S IOP=“Q” ; Force queu ing.
	10634	D ^%ZIS Q:P OP ; Sele ct Device
	10635	W !,“Finish ed with %Z IS.”
	10636	;
	10637	S ZTDTH=“@” ;Don’t sc hedule the task to r un, we’ll do it late r
	10638	; If we didn ’t need to set ZTDTH , we could use EN^XU TMDEVQ, bu t that
	10639	; I ‘new’s Z TDTH, so w e can’t se t it.
	10640	;
	10641	; BTW, Did y ou know th at there’s a 5th par ameter in EN^XUTMDEV Q?
	10642	; Usually, E N^XUTMDEVQ will ‘new ’ ZTSK, so you can’t get to it .
	10643	; If you put “1” as th e 5th para meter, ZTS K will exi st when EN returns.
	10644	; D EN^XUTMD EVQ(“PRINT ^ARHBQQ”,“ ARHB Print ”,.ZTSAVE, .%ZIS,1)
	10645	;
	10646	S ZTRTN=“PR INT^ARHBQQ ”
	10647	S ZTDESC=“A RHB Print”
	10648	D ^%ZTLOAD
	10649	D HOME^%ZIS
	10650	W !,“ZTSK=” ,$G(ZTSK)
	10651	Q :’$D(ZTSK)
	10652	S ARHZTSK=Z TSK
	10653	;
	10654	N ZTSAVE,%Z IS,ZTSK,ZT DTH,ZTRTN, ZTDESC,ZTI O,IOP
	10655	W !,“Now qu eue the fi rst task ( the gather task).”,!
	10656	; Now queue the first task, the “gather” p ortion of the job.
	10657	; Since we d on’t need a device,
	10658	; the user w ill only b e asked wh en to star t the task .
	10659	; (I wasn’t able to ge t EN^XUTMD EVQ to wor k for me. I tried s etting
	10660	; IOP=“Q;” t o let it k now that i t should b e queued a nd it didn ’t need
	10661	; a device, but it did nothing, and return ed a null ZTSK.)
	10662	F I=“ARHZTS K” S ZTSAV E(I)=“” ; Save the Z TSK of the “print” t ask.
	10663	S ZTIO=“” ; We don’t need a dev ice.
	10664	S IOP=“Q” ; Force que uing.
	10665	S ZTRTN=“GA THER^ARHBQ Q”
	10666	S ZTDESC=“A RHB Gather ”
	10667	D ^%ZTLOAD
	10668	D HOME^%ZIS
	10669	W !,“ZTSK=” ,$G(ZTSK)
	10670	Q
	10671	GATHER ;
	10672	N ARHJ
	10673	S ZTREQ=“@”
	10674	S ARHJ=“ARH B-QQ”_”-”_ $J_”-”_$H ; namespac e + unique ID
	10675	K ^XTMP(ARH J) ; Use ^ XTMP to pa ss a lot o f data bet ween tasks .
	10676	S ^XTMP(ARH J,0)=$$FMA DD^XLFDT(D T,1)_U_DT ; Save-thr u and crea te dates.
	10677	S ^XTMP(ARH J)=“HI MOM !” ; Prete nd this is a lot of data.
	10678	D SPRINT
	10679	Q
	10680	SPRINT ; Now sched ule the “p rint” task to run.
	10681	N ZTSK,ZTDT H,I,ZTRTN, ZTDESC,ZTI O,ZTSAVE ; Very impo rtant to N EW the
	10682	; input var iables to REQ^%ZTLOA D, otherwi se they re tain the v alues of
	10683	; the curre ntly runni ng task, a nd you cou ld uninten tionally c hange the
	10684	; “print” t ask to rer un the “ga ther” task .
	10685	F I=“ARHJ” S ZTSAVE(I )=“” ; Let the “prin t” task kn ow the “$J ” value.
	10686	S ZTSK=ARHZ TSK
	10687	S ZTDTH=$H
	10688	D REQ^%ZTLO AD
	10689	; Instead of the above 8 lines w e could ha ve simply:
	10690	; S X=$$REQQ ^XUTMDEVQ( ARHZTSK,$H ,“ARHJ”)
	10691	Q
	10692	PRINT ;
	10693	S ZTREQ=“@”
	10694	U IO ; Don’ t need thi s if invok ed using a ^XUTMDEVQ API.
	10695	W !,“The se cret messa ge is: ‘”, $G(^XTMP(A RHJ)),“‘”
	10696	K ^XTMP(ARH J)
	10697	Q
	10698
	10699	Code Execu tion
	10700	Figure 113 : ^%ZTLOAD API—Sampl e code exe cution
	10701	VAH>D ZTLO AD^ARHBQQ
	10702
	10703	Queue the second tas k (the pri nt task) f irst.
	10704	QUEUE TO P RINT ON
	10705	DEVICE: HO ME// P-MES S
	10706
	10707	1 P-MESSA GE-ENGWO-H FS-VXD H FS FILE == > MAILMESS AGE
	10708	2 P-MESSA GE-HFS-VXD HFS FIL E ==> MAIL MESSAGE
	10709	Choose 1-2 > 2 <Enter > P-MESSA GE-HFS-VXD HFS FILE ==> MAILM ESSAGE
	10710
	10711	Subject: M Y PRINT
	10712
	10713	Selec t one of t he followi ng:
	10714
	10715	M Me
	10716	P Postmaster
	10717
	10718	From whom: Postmaste r// <Enter >
	10719	Send mail to: XUUSER ,ONE// <En ter> XUUS ER,ONE
	10720	Select bas ket to sen d to: IN// <Enter>
	10721	And Send t o: <Enter>
	10722	Finished w ith %ZIS.
	10723	ZTSK=29214 97
	10724	Now queue the first task (the gather tas k).
	10725
	10726	Requested Start Time : NOW// <E nter> (JA N 25, 2005 @11:30:35)
	10727	ZTSK=29214 99
	10728
	10729	Output
	10730	Figure 114 : ^%ZTLOAD API—Sampl e output
	10731	Subj: MY P RINT [#28 881111] 01 /25/05@11: 30 2 line s
	10732	From: POST MASTER (Se nder: XUUS ER,ONE - C OMPUTER SP ECIALIST) In ‘IN’
	10733	basket.
	10734	Page 1 N ew
	10735	---------- ---------- ---------- ---------- ---------- ---------- ---------- ---------
	10736
	10737	The secret message i s: ‘HI MOM !’
	10738
	10739	Enter mess age action (in IN ba sket): Ign ore//
	10740
	10741	RTN^%ZTLOA D(): Find Tasks that Call a Ro utine
	10742	Reference Type:Suppo rted
	10743	Category:T askMan
	10744	ICR #:1006 3
	10745	Descriptio n:This API finds Tas kMan tasks that call a specifi c routine.
	10746	Format:RTN ^%ZTLOAD(r outine,lis t)
	10747	Input Para meters:rou tine:(requ ired) The name of th e specific routine c alled.
	10748	Output:lis t:Returns a list of TaskMan ta sks that c all the sp ecified ro utine.
	10749
	10750	$$S^%ZTLOA D(): Check for Task Stop Reque st
	10751	Reference Type:Suppo rted
	10752	Category:T askMan
	10753	ICR #:1006 3
	10754	Descriptio n:This ext rinsic fun ction is u sed within a task to determine if the ta sk has bee n asked to stop. Usi ng the $$S ^%ZTLOAD() function in longer tasks is h ighly reco mmended. T asks shoul d test $$S ^%ZTLOAD t o check if the user who queued the task has reques ted that t he task be stopped. If the tas k has been asked to stop, it s hould set the local variable Z TSTOP to 1 before qu itting. Th is alerts the subman ager to se t the task ’s status to STOPPED instead o f FINISHED , to give the user f eedback th at the tas k has obey ed their r equest.You can use t he optiona l message parameter to inform the user o f the prog ress of a job. It is displayed when the task is li sted by on e of the m any option s that lis t tasks.
	10755	Format:$$S ^%ZTLOAD([ message])
	10756	Input Para meters:mes sage:(opti onal) Allo ws you to leave a me ssage for the creato r of the T askMan tas k.
	10757	Output:ret urns:Retur ns:
	10758	1—Creator of the tas k that has asked the task to s top.
	10759	0—For all other case s.
	10760
	10761	STAT^%ZTLO AD: Task S tatus
	10762	Reference Type:Suppo rted
	10763	Category:T askMan
	10764	ICR #:1006 3
	10765	Descriptio n:This API looks up tasks and retrieves their curr ent status . The stat us of a ta sk returne d by STAT^ %ZTLOAD is expressed in the ge neral term s of wheth er the tas k ran, is running, o r runs. ZT SK(1) and (2) return the code and text o f the curr ent status . This sta tus is an abstractio n based on the more complex sy stem used by TaskMan .
	10766	An active task is on e that eit her is exp ected to s tart or is currently running. An inactiv e task doe s not star t in the f uture with out outsid e interven tion; this can be be cause it h as already completed , was neve r schedule d, or was interrupte d. The “ru nning” sta tus is not based on direct exa mination o f the syst em tables but is inf erred from TaskMan’s informati on about t he task.
	10767	When inter preting th e output o f STAT^%ZT LOAD, cons ider that:
	10768	If a task is transfe rred to an other volu me set, it becomes u ndefined o n the orig inal volum e set.
	10769	A status o f “running ” is a gue ss.
	10770	“Finished” does not necessaril y mean the task acco mplished w hat it set out to do .
	10771	An interru pted task may or may not run c orrectly i f edited a nd resched uled.
	10772	Format:STA T^%ZTLOAD
	10773	Make sure to perform the follo wing steps before ca lling this API:
	10774	NEW all no n-namespac ed variabl es.
	10775	Set all in put variab les.
	10776	Call the A PI.
	10777	Input Vari ables:ZTSK :(required ) The Task Man task n umber to l ook up. It must be d efined on the curren t volume s et.
	10778	Output Var iables:ZTS K(0):Retur ns:
	10779	1—Task is defined.
	10780	0—Task is not define d.
	10781	ZTSK(1):Nu meric stat us code fr om 0 to 5 indicating the statu s of the t ask.
	10782	ZTSK(2):St atus text describing the statu s of the t ask. Its v alue corre sponds wit h the stat us code in ZTSK(1). The possib le values and their meanings a re as foll ows:
	10783	ZTSK(1) = 0 and ZTSK (2) = “Und efined” me ans the ta sk does no t exist on this volu me set.
	10784	ZTSK(1) = 1 and ZTSK (2) = “Act ive: Pendi ng” means the task i s schedule d, waiting for an I/ O device, waiting fo r a volume set link, or waitin g for a pa rtition in memory.
	10785	ZTSK(1) = 2 and ZTSK (2) = “Act ive: Runni ng” means the task h as started running.
	10786	ZTSK(1) = 3 and ZTSK (2) = “Ina ctive: Fin ished” mea ns the tas k quit nor mally afte r running.
	10787	ZTSK(1) = 4 and ZTSK (2) = “Ina ctive: Ava ilable” me ans the ta sk was cre ated witho ut being s cheduled o r was edit ed without being res cheduled.
	10788	ZTSK(1) = 5 and ZTSK (2) = “Ina ctive: Int errupted” means the task was i nterrupted before it would hav e quit nor mally. Cau ses can in clude bad data, user intervent ion, hard error, and many othe r possibil ities.
	10789
	10790	$$TM^%ZTLO AD: Check if TaskMan is Runnin g
	10791	Reference Type:Suppo rted
	10792	Category:T askMan
	10793	ICR #:1006 3
	10794	Descriptio n:This ext rinsic fun ction dete rmines if TaskMan is running. Use this f unction if you need to know th e status o f TaskMan.
	10795	Format:$$T M^%ZTLOAD
	10796	Input Para meters:non e.
	10797	Output:ret urns:Retur ns:
	10798	1—TaskMan is running on the cu rrent volu me set.
	10799	0—TaskMan is not run ning on th e current volume set .
	10800
	10801	ZTSAVE^%ZT LOAD(): Bu ild ZTSAVE Array
	10802	Reference Type:Suppo rted
	10803	Category:T askMan
	10804	ICR #:1006 3
	10805	Descriptio n:This API stores a string of variables in the ZTS AVE array.
	10806	Format:ZTS AVE^%ZTLOA D(string_o f_variable s[,kill_zt save_flag] )
	10807	Input Para meters:str ing_of_var iables:(re quired) St ing of var iable name s to be st ored in th e ZTSAVE a rray.
	10808	kill_ztsav e_flag:(op tional) An y positive value fir st KILLs t he ZTSAVE array.
	10809	Output:ret urns:Store s the stri ng of inpu t variable s in the Z TSAVE arra y.
	10810
	10811
	10812	Toolkit: D eveloper T ools
	10813	Several to ols and Ap plication Programmin g Interfac es (APIs) are availa ble for de velopers t o work wit h Kernel T oolkit. Th is section describes these API s by type.
	10814	Toolkit—Da ta Standar dization
	10815	Overview
	10816	The API se t in this section ha s been dev eloped to support Da ta Standar dization’s effort to allow the mapping o f one term to anothe r term. Ma pping of t erms is do ne via the REPLACED BY VHA STA NDARD TERM field (#9 9.97) and provides t he high-le vel goals of the fol lowing:
	10817	Non-standa rd terms i nheriting standardiz ed charact eristics.
	10818	Deprecatin g a term a nd replaci ng it with a new ter m.
	10819	The Data S tandardiza tion API s et:
	10820	Maps one t erm to ano ther term.
	10821	Obtains th e term in which anot her term i s mapped.
	10822	Extracts f ield value s from the term in w hich anoth er term is mapped.
	10823	Shows the mapping re lationship s that a t erm has wi th other t erms.
	10824	Keywords:
	10825	VHA Unique ID (VUID)
	10826	Data Stand ardization
	10827	Term
	10828	Replacemen t Term
	10829	Replacemen t Relation ships
	10830	Use the fo llowing re placement relationsh ips to map the Data Standardiz ation API set in con text. Thes e APIs are documente d in this section:
	10831	Figure 115 : Toolkit— Replacemen t relation ships: Dat a standard ization
	10832	A --> B --> C - -> D A is repla ced by B G is re placed by C
	10833	^ ^ ^ ^ B is repla ced by C H is re placed by C
	10834	\| \ \| \ C is repla ced by D I is re placed by F
	10835	\| \ \| \ D has no r eplacement J is re placed by F
	10836	\| \ \| \ E is repla ced by A K is re placed by H
	10837	\| F \| H F is repla ced by A L is re placed by H
	10838	\| ^ ^ \| ^ ^
	10839	\| / \ \| / \
	10840	E I J G K L
	10841
	10842	$$GETRP LC(B) woul d return C
	10843
	10844	$$RPLCM NT(B) woul d return D
	10845
	10846	$$RPLCV ALS(J) wou ld return the reques ted field values fro m entry D
	10847
	10848	$$RPLCT RL(G) in b oth direct ions would return D and the ou tput array would
	10849	be set as follows :
	10850
	10851	OutArr (“BY”,A) = B OutArr(“FO R”,A,E) = “”
	10852	OutArr (“BY”,B) = C OutArr(“FO R”,A,F) = “”
	10853	OutArr (“BY”,C) = D OutArr(“FO R”,B,A) = “”
	10854	OutArr (“BY”,D) = “” OutArr(“FO R”,C,B) = “”
	10855	OutArr (“BY”,E) = A OutArr(“FO R”,C,G) = “”
	10856	OutArr (“BY”,F) = A OutArr(“FO R”,C,H) = “”
	10857	OutArr (“BY”,G) = C OutArr(“FO R”,D,C) = “”
	10858	OutArr (“BY”,H) = C OutArr(“FO R”,F,I) = “”
	10859	OutArr (“BY”,I) = F OutArr(“FO R”,F,J) = “”
	10860	OutArr (“BY”,J) = F OutArr(“FO R”,H,K) = “”
	10861	OutArr (“BY”,K) = H OutArr(“FO R”,H,L) = “”
	10862	OutArr (“BY”,L) = H
	10863
	10864	$$RPLCT RL(L) in t he forward direction would ret urn D and the output array
	10865	would b e set as f ollows:
	10866
	10867	OutArr (“BY”,C) = D OutArr(“FO R”,C,H) = “”
	10868	OutArr (“BY”,D) = “” OutArr(“FO R”,D,C) = “”
	10869	OutArr (“BY”,H) = C OutArr(“FO R”,H,L) = “”
	10870	OutArr (“BY”,L) = H
	10871
	10872	$$RPLCT RL(B) in t he backwar d directio n would re turn D and the outpu t array
	10873	would b e set as f ollows:
	10874
	10875	OutArr (“BY”,A) = B OutArr(“FO R”,A,E) = “”
	10876	OutArr (“BY”,E) = A OutArr(“FO R”,A,F) = “”
	10877	OutArr (“BY”,F) = A OutArr(“FO R”,B,A) = “”
	10878	OutArr (“BY”,I) = F OutArr(“FO R”,F,I) = “”
	10879	OutArr (“BY”,J) = F OutArr(“FO R”,F,J) = “”
	10880
	10881	$$RPLCL ST(G) in b oth direct ions would return D and the ou tput array would
	10882	be set as follows :
	10883
	10884	OutArr (1) = G ^ 0 OutArr(“IN DEX”,A) = 8
	10885	OutArr (2) = C ^ 0 OutArr(“IN DEX”,B) = 7
	10886	OutArr (3) = D ^ 1 OutArr(“IN DEX”,C) = 2
	10887	OutArr (4) = H ^ 0 OutArr(“IN DEX”,D) = 3
	10888	OutArr (5) = K ^ 0 OutArr(“IN DEX”,E) = 9
	10889	OutArr (6) = L ^ 0 OutArr(“IN DEX”,F) = 10
	10890	OutArr (7) = B ^ 0 OutArr(“IN DEX”,G) = 1
	10891	OutArr (8) = A ^ 0 OutArr(“IN DEX”,H) = 4
	10892	OutArr (9) = E ^ 0 OutArr(“IN DEX”,I) = 11
	10893	OutArr (10) = F ^ 0 OutArr(“IN DEX”,J) = 12
	10894	OutArr (11) = I ^ 0 OutArr(“IN DEX”,K) = 5
	10895	OutArr (12) = J ^ 0 OutArr(“IN DEX”,L) = 6
	10896
	10897	$$RPLCL ST(L) in t he forward direction would ret urn D and the output array
	10898	would b e set as f ollows if the status history w as also in cluded:
	10899
	10900	OutArr (1) = L ^ 0 OutArr(“IN DEX”,C) = 3
	10901	OutArr (1,3080101 .0954) = 0 OutArr(“IN DEX”,D) = 4
	10902	OutArr (2) = H ^ 0 OutArr(“IN DEX”,H) = 2
	10903	OutArr (2,3080101 .1308) = 1 OutArr(“IN DEX”,L) = 1
	10904	OutArr (2,3080105 .09) = 0
	10905	OutArr (3) = C ^ 0
	10906	OutArr (3,3080105 .0859) = 1
	10907	OutArr (3,3080112 .1722) = 0
	10908	OutArr (4) = D ^ 1
	10909	OutArr (4,3080112 .1723) = 1
	10910
	10911	$$RPLCL ST(B) in t he backwar d directio n would re turn D and the outpu t array
	10912	would b e set as f ollows:
	10913
	10914	OutArr (1) = A ^ 0 OutArr(“IN DEX”,A) = 1
	10915	OutArr (2) = E ^ 0 OutArr(“IN DEX”,E) = 2
	10916	OutArr (3) = F ^ 0 OutArr(“IN DEX”,F) = 3
	10917	OutArr (4) = I ^ 0 OutArr(“IN DEX”,I) = 4
	10918	OutArr (5) = J ^ 0 OutArr(“IN DEX”,J) = 5
	10919
	10920	Applicatio n Programm ing Interf aces (APIs )
	10921	$$GETRPLC^ XTIDTRM(): Get Mappe d Terms (T erm/Concep t)
	10922	Reference Type:Suppo rted
	10923	Category:T oolkit—Dat a Standard ization
	10924	ICR #:5078
	10925	Descriptio n:This ext rinsic fun ction gets the REPLA CED BY VHA STANDARD TERM field (#99.97) for a give n entry.
	10926	REF: For a n overview of the Da ta Standar dization A PI set, se e Toolkit— Data Stand ardization APIs.For a chart ma pping the Data Stand ardization API set i n context, see Repla cement Rel ationships .
	10927	Format:$$G ETRPLC^XTI DTRM(file, ien)
	10928	Input Para meters:fil e:(require d) File nu mber.
	10929	ien:(requi red) Inter nal Entry Number (IE N).
	10930	Output:ret urns:Retur ns the REP LACED BY V HA STANDAR D TERM fie ld (#99.97 ) for a gi ven entry.
	10931
	10932	Example
	10933	This extri nsic funct ion sets X to IEN_”; ”_FileNumb er of entr y that rep laces the input entr y:
	10934	>S X=$$GET RPLC^XTIDT RM(file,ie n)
	10935	NOTE:
	10936	Null is re turned on error. Thi s typicall y occurs w hen the in put entry does not e xist.
	10937	If the inp ut entry i s not repl aced by an other term then a re ference to the input term is r eturned.
	10938	$$RPLCLST^ XTIDTRM(): Get Repla cement Ter ms, w/Opti onal Statu s Date & H istory (Te rm/Concept )
	10939	Reference Type:Suppo rted
	10940	Category:T oolkit—Dat a Standard ization
	10941	ICR #:5078
	10942	Descriptio n:This ext rinsic fun ction trav erses the REPLACED B Y VHA STAN DARD TERM field (#99 .97) forwa rds and ba ckwards to find all terms that are repla cement ter ms for the input ent ry and all terms for which the input ent ry is a re placement. This is r ecursively done so t hat each p otential b ranch of r eplacement terms for wards and backwards is travers ed.
	10943	Format:$$R PLCLST^XTI DTRM(file, ien,drctn, statdate,s tathst,out arr)
	10944	Input Para meters:fil e:(require d) File nu mber.
	10945	ien:(requi red) Entry number.
	10946	drctn:(opt ional) Fla gs denotin g which di rection to follow th e trail of replaceme nt terms. Possible f lag values are:
	10947	F (default )—Follow t he trail f orwards.
	10948	B—Follow t he trail b ackwards.
	10949	*—Follow t he trail i n both dir ections (s ame as FB/ BF).
	10950	statdate:( optional) VA FileMan date/time in which to return term’s sta tus. Defau lts to cur rent date/ time.
	10951	stathst:(o ptional) F lag denoti ng if a te rm’s full status his tory shoul d be inclu ded in the output:
	10952	0 (default )—No.
	10953	1—Yes.
	10954	Input/Outp ut
	10955	Parameters :outarr:I: (required ) Array to put trail of replac ement term s into (cl osed root) .
	10956	O: The out put array contains t he list te rms to whi ch the inp ut entry i s somehow related.
	10957	OutArr(1.. n) = Term ^ StatusCo de (based on input S tatDate).
	10958	OutArr(1.. n,StatusDa teTime) - StatusCode on this d ate/time.
	10959	This node is only re turned if StatHst is set to “1 ” (Yes).
	10960	OutArr(“IN DEX”,Term) = 1..n.
	10961	NOTE: Term is in the format IE N;FileNumb er.StatusC ode:
	10962	1—Active.
	10963	0—Inactive .
	10964	StatusDate Time is in VA FileMa n format.
	10965	Example
	10966	This extri nsic funct ion sets X =IEN_”;”_F ileNumber of the ent ry that ul timately r eplaces th e input en try:
	10967	>S X=$$RPL CLST^XTIDT RM(File,IE N,Drctn,St atDate,Sta tHst,OutAr r)
	10968	NOTE:
	10969	Null is re turned on error. Thi s typicall y occurs w hen the in put entry does not e xist.
	10970	If the inp ut entry i s not repl aced by an other term then a re ference to the input term is r eturned.
	10971	$$RPLCMNT^ XTIDTRM(): M One Ter m to Anoth er (Term/C oncept)
	10972	Reference Type:Suppo rted
	10973	Category:T oolkit—Dat a Standard ization
	10974	ICR #:5078
	10975	Descriptio n:This ext rinsic fun ction recu rsively tr averses th e REPLACED BY VHA ST ANDARD TER M field (# 99.97) unt il the fin al replace ment term is reached .
	10976	Format:$$R PLCMNT^XTI DTRM(fle,i en)
	10977	Input Para meters:fil e:(require d) File nu mber.
	10978	ien:(requi red) Inter nal Entry Number (IE N).
	10979	Output:non e.
	10980
	10981	Example
	10982	This extri nsic funct ion sets X to IEN_”; ”_FileNumb er of the entry that ultimatel y replaces the input entry:
	10983	>S X=$$RPL CMNT^XTIDT RM(file,ie n)
	10984	NOTES:
	10985	Null is re turned on error. Thi s typicall y occurs w hen the in put entry does not e xist.
	10986	If the inp ut entry i s not repl aced by an other term then a re ference to the input term is r eturned.
	10987	$$RPLCTRL^ XTIDTRM(): Get Repla cement Tra il, w/ Rep laced “BY” & Replace ment “FOR” Terms
	10988	Reference Type:Suppo rted
	10989	Category:T oolkit—Dat a Standard ization
	10990	ICR #:5078
	10991	Descriptio n:This ext rinsic fun ction trav erses the REPLACED B Y VHA STAN DARD TERM field (#99 .97) forwa rds and ba ckwards to find all terms that are repla cement ter ms for the input ent ry and all terms for which the input ent ry is a re placement. This is r ecursively done so t hat each p otential b ranch of r eplacement terms for wards and backwards is travers ed.
	10992	Format:$$R PLCTRL^XTI DTRM(file, ien,drctn, outarr)
	10993	Input Para meters:fil e:(require d) File nu mber.
	10994	ien:(requi red) Inter nal Entry Number (IE N).
	10995	drctn:(opt ional) Fla gs denotin g which di rection to follow th e trail of replaceme nt terms. Possible f lag values are:
	10996	F (default )—Follow t he trail f orwards.
	10997	B—Follow t he trail b ackward.
	10998	*—Follow t he trail i n both dir ections (s ame as FB/ BF).
	10999	Input/Outp ut
	11000	Parameters :outarr:I: (required ) Array to put trail of replac ement term s into (cl osed root) .
	11001	O: The out put array contains t he trail o f replacem ent terms.
	11002	OutArr(“BY ”,Term) = Replacemen t Term mea ns: Entry “Term” is replaced B Y entry “R eplacement Term.”
	11003	OutArr(“FO R”,Replace ment Term, Term) = “ ” means: E ntry “Repl acement Te rm” is a r eplacement FOR entry “Term.”
	11004	Term and R eplacement Term is i n the form at IEN;Fil eNumber.
	11005
	11006	Example
	11007	This extri nsic funct ion sets X to IEN_”; ”_FileNumb er of the entry that ultimatel y replaces the input entry:
	11008	>S X=$$RPL CTRL^XTIDT RM(file,ie n,drctn,ou tarr)
	11009	NOTES:
	11010	Null is re turned on error. Thi s typicall y occurs w hen the in put entry does not e xist.
	11011	If the inp ut entry i s not repl aced by an other term then a re ference to the input term is r eturned.
	11012	$$RPLCVALS ^XTIDTRM() : Get Fiel d Values o f Final Re placement Term (Term /Concept)
	11013	Reference Type:Suppo rted
	11014	Category:T oolkit—Dat a Standard ization
	11015	ICR #:5078
	11016	Descriptio n:This ext rinsic fun ction retr ieves one or more fi elds of da ta from an entry’s f inal repla cement ter m. The REP LACED BY V HA STANDAR D TERM fie ld (#99.97 ) is recur sively tra versed unt il the fin al replace ment term is reached . The requ ested fiel ds of the final repl acement te rm are ret urned. It effectivel y bundles $$RPLCMNT^ XTIDTRM an d GETS^DIQ into a si ngle call.
	11017	Format:$$R PLCVALS^XT IDTRM(file ,ien,field s,flags,ou tarr)
	11018	Input Para meters:fil e:(require d) File nu mber.
	11019	ien:(requi red) Inter nal Entry Number (IE N).
	11020	fields:(re quired) Fi elds for w hich you w ish to get values.
	11021	REF: For detailed d escription , see the definition of the FI ELD parame ter in the GETS^DIQ API in the VA FileMa n Develope r’s Guide.
	11022	flags:(req uired) Fla gs that co ntrol outp ut format.
	11023	REF: For detailed d escription , see the definition of the FL AGS parame ter in the GETS^DIQ API in the VA FileMa n Develope r’s Guide.
	11024	Input/Outp ut:
	11025	Parameters outarr:Inp ut/Output:
	11026	I:(require d) Array t o put outp ut field v alues into (closed r oot).
	11027	O:The outp ut array i s in FDA f ormat.
	11028	REF: For example ou tput, see the GETS^D IQ API in the VA Fil eMan Devel oper’s Gui de.
	11029
	11030	Example
	11031	This extri nsic funct ion sets X to IEN_”; ”_FileNumb er of the entry that ultimatel y replaces the input entry:
	11032	>S X=$$RPL CVALS^XTID TRM(file,i en,fields, flags,outa rr)
	11033	NOTES:
	11034	Null is re turned on error. Thi s typicall y occurs w hen the in put entry does not e xist.
	11035	If an erro r occurs w hen extrac ting the r equested f ields from the final replaceme nt term th en a refer ence to th e final re placement term is st ill return ed and out arr is KIL Led.
	11036	If the inp ut entry i s not repl aced by an other term then a re ference to the input term is r eturned an d outarr( ) contains the field values fo r the inpu t entry.
	11037	$$SETRPLC^ XTIDTRM(): Set Repla cement Ter ms (Term/C oncept)
	11038	Reference Type:Suppo rted
	11039	Category:T oolkit—Dat a Standard ization
	11040	ICR #:5078
	11041	Descriptio n:This ext rinsic fun ction sets the REPLA CED BY VHA STANDARD TERM field (#99.97).
	11042	Format:$$S ETRPLC^XTI DTRM(file, ien,rplcmn t)
	11043	Input Para meters:fil e:(require d) File nu mber.
	11044	ien:(requi red) Inter nal Entry Number (IE N).
	11045	rplcmnt:(r equired) E ntry numbe r of repla cement ter m.
	11046	Output Var iables:X:R esults:
	11047	1 (success )—If point er to repl acement te rm stored.
	11048	0 (failure )—If unabl e to store pointer t o replacem ent term.
	11049
	11050	Example
	11051	This extri nsic funct ion sets X to 1 if P ointer to replacemen t term sto red (i.e., success) or 0 if Un able to st ore pointe r to repla cement ter m (i.e., f ailure):
	11052	>S X=$$SET RPLC^XTIDT RM(File,IE N,Rplcmnt)
	11053
	11054	Toolkit—Du plicate Re cord Merge
	11055	Overview
	11056	A file in which entr ies need t o be merge d can be e ntered in the DUPLIC ATE RESOLU TION file (#15.1). T his requir es adding the file a s one that can be se lected as the variab le pointer , and sear ch criteri a would us ually need to be spe cified to assist in identifyin g potentia l duplicat e pairs (a lthough an option ca n be used by which s elected pa irs can be added dir ectly to t he DUPLICA TE RECORD file (#15) as verifi ed duplica tes). Veri fied dupli cate pairs may be ap proved for merging, and a merg e process generated for those approved p airs. A DU PLICATE RE CORD file (#15) entr y also has handle fi les that a re not ass ociated as normal po inters ide ntified in the PACKA GE file (# 9.4) under the AFFEC TS RECORD MERGE subf ile with s pecial pro cessing ro utines.
	11057	CAUTION: I f a file h as related files tha t are not normal poi nters, the y should b e handled only as en tries in t he duplica te record file and t he Kernel Toolkit op tions used for merge s involvin g the file .
	11058	The merge utility of Kernel To olkit as r evised by Kernel Too lkit patch XT7.323 provides an entry p oint that is availab le to deve lopers for the mergi ng of one or more pa irs of rec ords (a FR OM record and a TO r ecord) in a specifie d file. Th e merge pr ocess merg es the dat a of the F ROM record into that of the TO record an d deletes the FROM r ecord, res toring by a hard set only the zero node with the . 01 value o n it until the merge process i s complete d (such th at any ref erences to that loca tion via p ointers do es not err or out). A ny files t hat contai n entries DINUMed wi th the dat a pairs ar e then als o merged ( and any fi les that a re related to them b y DINUM as well). An y pointers that can be identif ied rapidl y by cross -reference s are modi fied so th at referen ces for th e FROM ent ry become references to the TO entry ins tead. Foll owing this , any file s that con tain other pointers are search ed entry b y entry to test for pointers t o a FROM e ntry, and when found are modif ied to ref erence the TO entry. This sear ch for poi nter value s is the m ost time c onsuming p art of the entire pr ocess and may take a n extended period de pending up on the num ber of fil es that mu st be sear ched, the number of entries in those fil es, and ho w many lev els at whi ch subfile s pointers may be lo cated. Sin ce the sea rch throug h these fi les takes the same p eriod of t ime indepe ndent of t he number of pairs t hat are be ing merged , it is su ggested th at as many pairs as convenient be combin ed in one process. A t the end of the con version of these poi nters, the zero node stubs are removed f rom the pr imary file and all r elated DIN UMed files .
	11059	The merge process is a single job that i s tracked with frequ ent update s on locat ion and st atus from start to f inish. The job can b e stopped at any tim e if neces sary using TaskMan u tilities ( or in the event of a system cr ash, etc.) and resta rted at th e point of interrupt ion at a l ater time.
	11060	Manner in which data is Merged
	11061	When a pri mary file or a DINUM ed files e ntries are merged, a ny top lev el (single value) fi elds that are presen t in the F ROM entry that are n ot present in the TO entry is merged int o the TO e ntries dat a. Any of these fiel ds that co ntain cros s-referenc es are ent ered using a VA File Man utilit y (FILE^DI E) so that the cross -reference s are fire d. Other f ields (tho se without cross-ref erences) a re directl y set into the data global.
	11062	If a subfi le entry ( Multiple) exists in the FROM r ecord that is not pr esent in t he TO reco rd (as ide ntified by the .01 v alue), tha t entry is created w ith a VA F ileMan uti lity (UPDA TE^DIE) an d the rest of the su bfile merg ed over in to the TO record and the cross -reference s within t he subfile and any d escendent subfiles r un.
	11063	If a subfi le entry ( Multiple) exists in the FROM r ecord and an identic al .01 val ue exists in the TO record, th e subfile in the FRO M record i s searched for any d escendent subfiles t hat are no t present in the TO record sub file. If s uch a subf ile is fou nd it is m erged into the subfi le in the TO record and any cr oss-refere nces in th e merged s ubfile run .
	11064	For fields that are simple poi nters to t he primary file (or any other file DINUM ed to the primary fi le) the re ference to the FROM record is changed to a referen ce to the TO record. If the fi eld contai ns a cross -reference this edit ing is per formed usi ng a VA Fi leMan Util ity call ( FILE^DIE), otherwise it is set directly into the g lobal node .
	11065	Developing a File Me rge Capabi lity
	11066	This topic provides developers with a se t of instr uctions to follow in building a merge ca pability f or a file. After a d eveloper i dentifies a file tha t has a su bstantial number of duplicates and that the nature and use o f the file warrants a merge ut ility, he/ she then f ollows the steps out lined in t his sectio n in devel oping that merge cap ability.
	11067	For demons tration pu rposes, th e rest of this secti on uses a specific e xample of developing a Patient Merge usi ng the Dup licate Res olution Ut ilities.
	11068	Step 1
	11069	Notify the Kernel To olkit deve lopers of the percei ved need f or a dupli cate check ing/merge capability for a par ticular fi le. They w ill do the following :
	11070	Assists th e develope r in decid ing whethe r there is indeed a need for a Duplicate Resolutio n Utility for this p articular file.
	11071	Add the fi le to the .01 and .0 2 variable pointer f ield defin itions in the DUPLIC ATE RECORD file (#15 ).
	11072	Notifies t he applica tion devel oper when the modifi ed diction ary is to be release d to the f ield.
	11073	Step 2
	11074	The develo per needs to now com municate t o the larg er develop ment commu nity his/h er intenti on to deve lop a merg e capabili ty for thi s file. Al l develope rs need to determine if the me rging and deleting o f records in this fi le affects their pac kage in su ch a way t hat they n eed to hav e their ow n unique m erge routi ne that de als with o nly their package's files. A d eveloper u sually has to write their own unique mer ge routine if any of the follo wing condi tions exis t:
	11075	Patient po inter fiel d is defin ed as a nu meric or f ree text f ield rathe r than a p ointer.
	11076	Developer wants thei r end user s to compl ete some t ask prior to the mer ge occurri ng.
	11077	There are compound c ross refer ences that include t he patient pointer o n another field but the cross reference is not tri ggered by the changi ng of the patient po inter.
	11078	Merge (Dup licate Res olution Ut ilities) d oes not do what the package de veloper de sires.
	11079	Descriptio n of What Occurs dur ing the Me rge
	11080	The follow ing is a b rief descr iption of what occur s during t he merge p rocess:
	11081	The base f ile (e.g., PATIENT f ile, #2) i s checked to see if it exists.
	11082	The PT nod es (e.g., ^DD(2,0,"P T",) are c hecked and any false positives are remov ed.
	11083	Creates a list of fi les and fi elds withi n those fi les that p oint to th e file bei ng merged (e.g., in this examp le the fil e being me rged is th e PATIENT file, #2).
	11084	If a file is pointin g to the f ile being merged by its .01 fi eld, and i f that .01 field is DINUM, the n all file s/fields t hat point to that fi le are als o gathered . The DINU M rule als o applies to that fi le and any files poi nting to i t, to any depth.
	11085	Each file/ field is c hecked and re-pointe d/merged a s follows:
	11086	If the fie ld pointin g is not a .01 field , the "FRO M entry" i s changed to the "TO entry".
	11087	If the fie ld pointin g is the . 01 field b ut not DIN UM, the "F ROM entry" is change d to the " TO entry".
	11088	Each point ing .01 DI NUM field is handled as follow s:
	11089	If the .01 DINUM fie ld is at t he file le vel, ^DIT0 is called to merge the "FROM entry" to the "TO en try" and t hen the "F ROM entry" is delete d. ^DIT0 m erges fiel d by field but does not change any value in the "T O entry". That means that NULL fields in the "TO e ntry" get the value from the s ame field in the "FR OM entry" if it is n ot NULL, a nd valued fields in the "TO en try" remai n the same . ^DIT0 al so merges Multiples. If a Mult iple entry in the "F ROM entry" cannot be found in the "TO en try", it i s added to the "TO e ntry". If a Multiple entry in the "FROM entry" can be found in the "TO entry", t hen that M ultiple en try is mer ged field by field.
	11090	If the .01 DINUM fie ld is at t he subfile level (in a Multipl e), it is handled as follows:
	11091	If there i s a "FROM entry" but no "TO en try", the "FROM entr y" is adde d to the " TO entry", changing the .01 fi eld value in the pro cess, and the "FROM entry" is deleted.
	11092	If there i s a "FROM entry" and also a "T O entry", the "FROM entry" is deleted an d the "TO entry" rem ains uncha nged.
	11093	If it is d etermined that a dev eloper mus t have the ir own uni que merge that deals with thei r files, t hey must m ake the ap propriate entries in the PACKA GE file (# 9.4). If t hey have t o have som e sort of action tak en by end- users prio r to the m erging of the record s, they mu st update the MERGE PACKAGES M ultiple in the DUPLI CATE RECOR D file (#1 5) for tha t pair of records.
	11094	Entries Ne eded in th e PACKAGE File (#9.4 )
	11095	In the PAC KAGE file (#9.4) mak e entries in the fol lowing fie lds:
	11096	AFFECTS RE CORD MERGE field (#2 0)
	11097	.01 field— Enter the file affec ted (e.g., PATIENT f ile, #2)
	11098	NAME OF ME RGE ROUTIN E field—En ter the na me of the merge rout ine, which is execut ed via ind irection b y Duplicat e Resoluti on Utiliti es.If you leave this field bla nk but sti ll place a n entry in the PACKA GE file (# 9.4), Dupl icate Reso lution Uti lities ass umes that you have s ome sort o f interact ive merge process th at your en d-users mu st complet e prior to the main merging of the two r ecords. It also assu mes that t his intera ctive merg e process is on a se parate opt ion within the devel oper's pac kage optio ns. The va lues of th e two reco rds being merged are placed in :
	11099	^TMP("XDRM RGFR",$J,X DRMRG("FR" ),
	11100	^TMP("XDRM RGTO",$J,X DRMRG("TO" ),
	11101	These shou ld be refe renced by the develo per if the y need any certain f ield value s since th e values m ight have been chang ed prior t o the exec ution of t heir merge routine.
	11102	RECORD HAS PACKAGE D ATA field— Enter a st ring of M executable code that is passed the varia ble XDRMRG ("FR") (th e "FROM re cord" IEN) and set X DRZ to 0. The code s hould set XDRZ=1 if XDRMRG("FR ") has dat a within y our packag e files.
	11103	Remember t o only mak e these en tries in t he PACKAGE file (#9. 4) if the normal mer ge does no t suffice for your p ackage. If you have an entry i n the PACK AGE file ( #9.4) the repointing and mergi ng as desc ribed abov e does not take plac e for thos e files wi thin your Package en try.
	11104	At the com pletion of your inte ractive me rge proces s the deve loper must set the S TATUS fiel d of the M ERGE PACKA GES Multip le for the ir package in the DU PLICATE RE CORD file (#15) entr y to Ready . This mus t be done using VA F ileMan, be cause of t he trigger that is o n the STAT US field. Once all o f the MERG E PACKAGE entries ha ve a STATU S of Ready , the main merging o f the two records ca n occur.
	11105	Step 3
	11106	The develo per needs to add an entry in t he DUPLICA TE RESOLUT ION file ( #15.1) for the file being buil t. The fol lowing fie lds need t o be updat ed in the DUPLICATE RESOLUTION file (#15 .1) and da ta should be entered by the de veloper:
	11107	.01 FILE T O BE CHECK ED (requir ed)
	11108	.06 CROSS- REF FOR NE W SEARCH ( optional)
	11109	.09 CANDID ATE COLLEC TION ROUTI NE (requir ed)
	11110	.11 DUPLIC ATE MANAGE R MAIL GRO UP (option al)
	11111	.15 POTENT IAL DUPLIC ATE THRESH OLD% (requ ired)
	11112	.16 VERIFI ED DUPLICA TE MAIL GR OUP (optio nal)
	11113	.17 VERIFI ED DUPLICA TE MSG ROU TINE (opti onal)
	11114	.18 VERIFI ED DUPLICA TE THRESHO LD% (optio nal)
	11115	.25 MERGE STYLE (req uired)
	11116	.26 DELETE FROM ENTR Y (optiona l)
	11117	.27 PRE-ME RGE ROUTIN E (optiona l)
	11118	.28 POST-M ERGE ROUTI NE (option al)
	11119	.29 MERGE MAIL GROUP (optional )
	11120	.31 MERGE MSG ROUTIN E (optiona l)
	11121	.33 MERGE DIRECTION INP TRANSF ORM (optio nal)
	11122	1100 DUPLI CATE TESTS (required )
	11123	.01 DUPLIC ATE TEST ( required)
	11124	.02 ORDER OF TEST (r equired)
	11125	.03 DUPLIC ATE TEST R OUTINE (re quired)
	11126	.04 FILE F OR INFORMA TION (opti onal)
	11127	.05 FIELD TO BE CHEC KED (requi red)
	11128	.06 SUCCES SFUL MATCH WEIGHT (r equired)
	11129	.07 UNSUCC ESSFUL MAT CH WEIGHT (required)
	11130	1200 DINUM FILES FOR MERGE (op tional)
	11131	.01 DINUM FILES FOR MERGE (opt ional)
	11132	Explanatio n of Field s in Logic al Order o f Entry
	11133	Selected f ields are explained in the log ical order of entry versus str ict numeri c field or der as fol lows:
	11134	.01 FILE T O BE CHECK ED
	11135	Enter the file for w hich the d eveloper w ants to ch eck and me rge duplic ates. You can only e nter files that are also defin ed in the .01 variab le pointer field of the DUPLIC ATE RECORD file (#15 ). If the file you a re interes ted in is not there, contact t he Kernel Toolkit te am for coo rdination.
	11136	.09 CANDID ATE COLLEC TION ROUTI NE
	11137	This field is update d with the name of t he routine that the Duplicate Resolution Utilities executes to generat e the list of potent ial duplic ate candid ates. The list of ca ndidates i s passed b ack to the merge she ll in ^TMP (“XDRD”,$J ,file numb er. For ex ample, if this is a patient me rge utilit y, the can didate col lection ro utine migh t pass bac k, to the merge shel l, all pat ients who have the s ame last n ame as the record be ing proces sed, the s ame DOB as the recor d being pr ocessed, o r who have the same or similar Social Se curity Num ber (SSN). This cand idate coll ection rou tine is us ed to mini mize the n umber of r ecords the merge she ll has to process in determini ng potenti al duplica tes.
	11138	REF: For a n example of a Candi date Colle ction rout ine, see t he “Candid ate Collec tion Routi ne for Pat ient Merge Example” section.
	11139	Selecting Fields to Compare in Candidate Collectio n:
	11140	The develo per needs to give th is conside rable thou ght as sel ecting wro ng fields for candid ate collec tion resul ts in miss ed or many false pot ential dup licate can didates.
	11141	The most i mportant c haracteris tic that a field sho uld have i s the prob ability of containin g data. If a SSN fie ld exists in a file but the fi eld is rar ely filled in, it wo uld not be a good fi eld from w hich to bu ild candid ates.
	11142	Since sele ction of c andidates deals with minimizin g the set of records to test f urther, lo ok at the whole file initially . It becom es desirab le for the field to have a cro ss referen ce.
	11143	Uniqueness of a fiel d is also important. If all re cords cont ain one of two possi ble values (e.g., Ma le or Fema le), it ma kes little sense for you to se lect all r ecords tha t are the same value as the re cord compa red. Howev er, such a field can be useful later in performing individua l tests.
	11144	One final point to k eep in min d is, if y ou finally come up w ith very f ew fields to collect candidate s on, you may need t o be very liberal in the compa rison. Fur thermore, you might want to ma ke more th an one pas s through the same f ield with different comparison logic, ho ping to fi nd additio nal record s that we missed ini tially.
	11145	1100 DUPLI CATE TESTS
	11146	The develo per must i dentify da ta items/f ields to b e used to assist in determinin g if a pai r of recor ds are dup licates. T hese items /fields mu st be sing le valued fields (i. e., data i n multiple fields is not suppo rted), as follows:
	11147	.01 DUPLIC ATE TEST
	11148	This is a free text name for t he test (e .g., Name, SSN, and DOB).
	11149	.02 ORDER OF TEST
	11150	Enter in t he numeric value of the order you want t he tests e xecuted.
	11151	.03 DUPLIC ATE TEST R OUTINE
	11152	Enter the name of th e routine that is ca lled to do the actua l comparis on of the two record s for a sp ecific fie ld.
	11153	REF: For e xamples of duplicate test rout ines, see the “Dupli cate Test Routine Ex amples” se ction.
	11154	Figure 116 : .03 DUPL ICATE TEST ROUTINE—V ariables p assed to t he test ro utine
	11155	Variable
	11156	Value
	11157	XDRCD
	11158	IEN of Rec ord 1.
	11159	XDRCD2
	11160	IEN of Rec ord 2.
	11161	XDRFL
	11162	File numbe r being ch ecked
	11163	XDRDTEST(x drdto
	11164	zero node of the tes t entry fr om the DUP LICATE RES OLUTION fi le (#15.1)
	11165	XDRDCD(XDR FL,XDRCD,f ield numbe r,"I")
	11166	Internal d ata value for this f ield for R ecord 1.
	11167	XDRDCD2(xd rfl,xdrcd2 ,field num ber,"I")
	11168	Internal d ata value for this f ield for R ecord 2.
	11169	XDRD("test score")
	11170	0; This va riable is used to pa ss the tes t score ba ck to XDRD UP.
	11171
	11172	The succes sful maxim um score c an be obta ined from the follow ing:
	11173	$P(XDRDTES T(xdrdto), U,6)
	11174
	11175	The unsucc essful sco re can be obtained f rom the fo llowing:
	11176	$P(XDRDTES T(xdrdto), U,7)
	11177
	11178	Within the duplicate test rout ine, the d eveloper c an assign the entire successfu l match we ight if bo th records ’ data is exactly th e same, or he can as sign a per centage of the match score if the data i s similar, but not e xactly the same. For example, if record 1 has a NA ME of XUPA TIENT,ONE- TWO and re cord 2 has a NAME of XUPATIENT ,ONE and t he success ful match weight for NAME is 5 0 points, this pair might be a ssigned 90 % of the t otal 50 po ints. The developers have to g o through trial and error meth ods of cha nging and calculatin g the perc ent of the total mat ch score t hat is ass igned.
	11179	REF: For e xamples of duplicate test rout ines, see the “Dupli cate Test Routine Ex amples” se ction.
	11180	.04 FILE F OR INFORMA TION
	11181	If the fie ld that is being tes ted is not in the ba se file be ing checke d, the dev eloper mus t enter th e file whe re the inf ormation i s stored. For exampl e, in the Indian Hea lth Servic e (IHS) Pa tient Merg e, the TRI BE OF MEMB ERSHIP is a field us ed for a d uplicate t est, and t his data f ield is st ored in th e IHS PATI ENT file ( #2). If no entry is made in th is field, the Merge (Duplicate Resolutio n Utilitie s) assumes the base file.
	11182	.05 FIELD TO BE CHEC KED
	11183	This field contains the field number of the data b eing used for this t est. The d eveloper m ust be awa re that Mu ltiple fie lds cannot be used f or duplica te tests.
	11184	.06 SUCCES SFUL MATCH WEIGHT
	11185	This is th e score or total num ber of poi nts assign ed when a match is m ade on the data item being che cked. This score can be anywhe re from 0 to 99. The developme nt team ne eds to det ermine the level of confidence associate d with eac h test. Th e higher c onfidence fields wou ld be assi gned a gre ater succe ssful matc h score th an the low er confide nce fields . For exam ple, in a Patient Me rge, if NA ME matches exactly, a total of 60 points might be given, but if SEX or TRIBE OF MEMBERSHIP match exa ctly only 10 points is given. The total number of points bet ween all t he tests d oes not ha ve to equa l 100. The calculati ons to det ermine whe ther or no t the pair is a pote ntial dupl icate is b ased on a percentage of the to tal possib le score. If a data item is mi ssing, it does not f igure in t he denomin ator in ca lculating the percen tage.
	11186	.07 UNSUCC ESSFUL MAT CH WEIGHT
	11187	This is th e score or total num ber of poi nts assign ed when th e data ite ms for the two recor ds being c hecked do not match. This scor e is norma lly a nega tive numbe r. For exa mple, if t he DOB for the two r ecords is different, a score o f -40 migh t be assig ned. This score can be anywher e from 0 t o -99. The developme nt team ne eds to det ermine the level of confidence associate d with eac h test. Th e higher c onfidence fields wou ld be assi gned a gre ater negat ive unsucc essful mat ch score t han the lo wer confid ence field s.
	11188	.15 POTENT IAL DUPLIC ATE THRESH OLD%
	11189	This is th e possible percentag e out of 1 00 after t he accumul ation of t he test sc ores. If t he final a ccumulated test scor e is equal to or gre ater than this perce ntage of t he total p ossible po ints, the record pai r is added to the DU PLICATE RE CORD file (#15) as a potential duplicate pair. The percentag e has to b e experime nted with to find th e best per centage to use. It i s recommen ded that t he percent age be set low at fi rst and gr adually in creased to find the best possi ble percen tage, so t hat you do not have a large nu mber of fa lse negati ves.
	11190	.25 MERGE STYLE
	11191	This deter mines whet her or not the merge process i s to be in teractive or not. It is highly recommend ed that th e merge be interacti ve. If it is interac tive, the user is ab le to sele ct fields from both the "from" and the " target" re cord. If n on-interac tive, all values are taken fro m the sour ce record.
	11192	.11 DUPLIC ATE MANAGE R MAIL GRO UP
	11193	This field contains a pointer to the mai l group th at receive s messages in cases when the d uplicate c hecking pr ocess coul d not be s tarted. So me example s of condi tions that would gen erate bull etins incl ude:
	11194	Test routi ne is not present.
	11195	No entry i n the DUPL ICATE RESO LUTION fil e (#15.1) for this f ield.
	11196	Global roo t node in ^DIC is un defined.
	11197	.16 VERIFI ED DUPLICA TE MAIL GR OUP
	11198	This field contains a pointer to the mai l group th at receive s messages when a pa ir of reco rds have b een verifi ed as dupl icates. Fo r example, in the ca se of a pa tient merg e, there m ight be th ings that pharmacy o r lab staf f want to do before the two re cords are merged.
	11199	.17 VERIFI ED DUPLICA TE MSG ROU TINE
	11200	This field allows a software d eveloper t o send a c ustomized bulletin n otifying t he Verifie d Duplicat e Mail Gro up about v erified du plicates. If nothing is entere d, the Ker nel Duplic ate Resolu tion softw are sends a brief bu lletin to the member s of the m ail group. This bull etin only provides t he .01 val ue and the DFN numbe rs of the two record s. The Dup licate Res olution so ftware pas ses the XD RMFR and X DRMTO rout ines and i t is up to this rout ine to gat her any ot her inform ation it w ants to se nd in the bulletin a nd also to send the bulletin t o the Veri fied Dupli cate Mail Group. A l abel entry point is allowed bu t you must use a “-” instead o f the norm al “^” (e. g., ENTRY POINT-).
	11201	.29 MERGE MAIL GROUP
	11202	This field contains a pointer to the mai l group th at receive s messages when a pa ir of reco rds have b een merged . Generall y, this is the same mail group as the VE RIFIED DUP LICATE MAI L GROUP (# .16). Thes e recipien ts can exa mine the m erged-to r ecord to m ake sure t hat all da ta transfe rred from the merged -from reco rd success fully.
	11203	.31 MERGE MSG ROUTIN E
	11204	This field is allows a softwar e develope r to send a customiz ed bulleti n notifyin g the Merg e Mail Gro up about m erged dupl icate pair s. If noth ing is ent ered, the Kernel Dup licate Res olution so ftware sen ds a brief bulletin to the mem bers of th e mail gro up. The Ke rnel Bulle tin only p rovides th e .01 valu es and the DFN's of the two re cords. The Duplicate Resolutio n software passes th e XDRMFR a nd XDRMTO routines a nd it is u p to the r outine to gather any informati on it want s to send in the bul letin and also to se nd the bul letin to t he Merge M ail Group. A label e ntry point is allowe d but you must use a “-” inste ad of the normal “^” (e.g., EN TRY POINT- ROUTINE). This entry point is executed b y the Dupl icate Reso lution sof tware afte r transfor ming the “ -” into a “^”.
	11205	Also, this routine m ight very well need to be diff erent from the VERIF IED DUPLIC ATE MSG RO UTINE (#.1 7), becaus e the info rmation th at users n eed to see after the merge is different from befor e.
	11206	.18 VERIFI ED DUPLICA TE THRESHO LD%
	11207	If this fi eld contai ns a perce ntage from 0 to 100, the Dupli cate Resol ution Util ities (XDR namespace ) software automatic ally marks the two r ecords as Verified D uplicates if the com parison sc ore percen tage is eq ual or gre ater to th is value. This numbe r, if ente red, needs to be som ewhat high , probably above 90% (e.g., IH S does not use this field in t he case of the patie nt merge, because th ey would l ike human determinat ion if the two recor ds are ind eed duplic ates).
	11208	Special Pr ocessing R outine Exa mples
	11209	Candidate Collection Routine f or Patient Merge Exa mple
	11210	Figure 117 : Special Processing Routine E xamples—Ca ndidate Co llection R outine for Patient M erge
	11211	DPTDCAN;IH S/OHPRD/JC M - GETS P OSSIBLE DU PLICATE CA NDIDATES ; 09/16/93/ 08:19
	11212	;;1.0;DPTD ;;
	11213	;
	11214	; Calls: E N^DIQ1
	11215	;
	11216	START;
	11217	K ^TMP("XD RD",$J,XDR FL),DPTDCA N
	11218	Q:$P(^DPT( XDRCD,0),U ,19)
	11219	D VALUE
	11220	D NAME
	11221	D SSN
	11222	D DOB
	11223	ENDD EOJ
	11224	Q
	11225	;
	11226	VALUE;
	11227	S DIC=2,DA =XDRCD,DIQ (0)="I",DI Q="DPTDCAN ",DR=".01; .03;.09"
	11228	D EN^DIQ1 K DIC,DA,D R,DIQ
	11229	Q
	11230	;
	11231	NAME;Get p atients wi th the sam e last nam e and firs t initial
	11232	G:DPTDCAN( XDRFL,XDRC D,.01,"I") ']"" NAMEX
	11233	S DPTDCAN( "NAME")=DP TDCAN(XDRF L,XDRCD,.0 1,"I")
	11234	S DPTDCAN( "LNAME&FI" )=$P(DPTDC AN("NAME") ,",",1)_", "_$E($P(DP TDCAN("NAM E"
	11235	),",",2),1 )_"AAA"
	11236	S DPTDCAN( "BNAME")=D PTDCAN("LN AME&FI")
	11237	F I=0:0 S DPTDCAN("B NAME")=$O( ^DPT("B",D PTDCAN("BN AME"))) Q: DPTDCAN("B NA
	11238	ME")=""!(( $P(DPTDCAN ("NAME")," ,",1)_","_ $E($P(DPTD CAN("NAME" ),",",2),1 )
	11239	)'=($P(DPT DCAN("BNAM E"),",",1) _","_$E($P (DPTDCAN(" BNAME"),", ",2),1)))
	11240	D
	11241	. S DPTDCA N("BNAMEDF N")=0 F S DPTDCAN(" BNAMEDFN") =$O(^DPT(" B",DPTDCAN ("
	11242	BNAME"),DP TDCAN("BNA MEDFN"))) Q:DPTDCAN( "BNAMEDFN" )="" S:DP TDCAN("BNA M
	11243	EDFN")'=XD RCD ^TMP(" XDRD",$J,X DRFL,DPTDC AN("BNAMED FN"))="".
	11244	QNAMEXQ
	11245	;
	11246	SSN;Get pa tients wit h same las t four dig its of ssn
	11247	G:DPTDCAN( XDRFL,XDRC D,.09,"I") ']"" SSNX
	11248	S DPTDCAN( "SSN")=DPT DCAN(XDRFL ,XDRCD,.09 ,"I")
	11249	S DPTDCAN( "L4SSN")=$ E(DPTDCAN( "SSN"),6,9 )
	11250	S DPTDCAN( "BL4SSN")= XDRCD
	11251	F %=0:0 S DPTDCAN("B L4SSN")=$O (^DPT("BS" ,DPTDCAN(" L4SSN"),DP TDCAN("BL4 SS
	11252	N"))) Q:'D PTDCAN("BL 4SSN") S ^TMP("XDRD ",$J,XDRFL ,DPTDCAN(" BL4SSN"))= ""
	11253	;
	11254	; Check SS NS with sa me first f ive digits
	11255	; Commente d out the following line, is n ot specifi c enough f or IHS
	11256	; but woul d be usefu l for the VA
	11257	;
	11258	;S DPTDCAN ("F5SSN")= $E(DPTDCAN ("SSN"),1, 5)_"0000", DPTDCAN("5 SSN")=DPTD CA
	11259	N("F5SSN") D
	11260	. F %=0:0 S DPTDCAN( "5SSN")=$O (^DPT("SSN ",DPTDCAN( "5SSN"))) Q:DPTDCAN( "5
	11261	SSN")'=+DP TDCAN("5SS N")!($E(DP TDCAN("5SS N"),1,5)'= $E(DPTDCAN ("SSN"),1, 5
	11262	)) S ^TMP ("DPTDCAN" ,$J,XDRFL, $O(^DPT("S SN",DPTDCA N("5SSN"), "")))=""
	11263	. Q
	11264	SSNXQ
	11265	;
	11266	DOB;Get pa tients wit h same dat e of birth
	11267	G:DPTDCAN( XDRFL,XDRC D,.03,"I") ']"" DOBX
	11268	S DPTDCAN( "DOB")=DPT DCAN(XDRFL ,XDRCD,.03 ,"I")
	11269	S DPTDCAN( "BDOB")=XD RCD
	11270	F %=0:0 S DPTDCAN("B DOB")=$O(^ DPT("ADOB" ,DPTDCAN(" DOB"),DPTD CAN("BDOB" ))
	11271	) Q:'DPTDC AN("BDOB") S ^TMP(" XDRD",$J,X DRFL,DPTDC AN("BDOB") )=""
	11272	;
	11273	;Transpose day of bi rth and ge t patients with same date of b irth
	11274	;
	11275	S DPTDCAN( "TDOB")=$E (DPTDCAN(" DOB"),1,5) _$E(DPTDCA N("DOB"),7 )_$E(DPTDC AN
	11276	("DOB"),6)
	11277	S DPTDCAN( "BDOB")=XD RCD
	11278	F %=0:0 S DPTDCAN("B DOB")=$O(^ DPT("ADOB" ,DPTDCAN(" TDOB"),DPT DCAN("BDOB ")
	11279	)) Q:'DPTD CAN("BDOB" ) S ^TMP( "XDRD",$J, XDRFL,DPTD CAN("BDOB" ))=""
	11280	DOBXQ
	11281	;
	11282	EOJ;
	11283	K DPTDCAN, %
	11284	Q
	11285
	11286	Duplicate Test Routi ne Example s
	11287
	11288	Name Test Routine fo r a Patien t Merge Ex ample
	11289	Figure 118 : Special Processing Routine E xamples—Na me Test Ro utine for a Patient Merge
	11290	DPTDN;IHS/ OHPRD/JCM; COMPARES N AMES; [ 06 /08/92 12 :14 PM ]
	11291	;;1.0;DPTD ;;AUG 13, 1991
	11292	;
	11293	; Calls: S OU^DICM1
	11294	;
	11295	START;
	11296	D INIT
	11297	D NAME
	11298	I $O(^DPT( XDRCD,.01, 0)) D OTHE R
	11299	ENDD EOJ
	11300	Q
	11301	;
	11302	EN; EP - E ntry Point for any r outines co mparing na mes
	11303	;
	11304	D INIT1
	11305	D COMPARE
	11306	D EOJ
	11307	Q
	11308	;
	11309	INIT;
	11310	D EOJ
	11311	S DPTDN("M ATCH")=$P( XDRDTEST(X DRDTO),U,6 )
	11312	S DPTDN("N O MATCH")= $P(XDRDTES T(XDRDTO), U,7)
	11313	S DPTDN=$G (XDRCD(XDR FL,XDRCD,. 01,"I")),D PTDN2=$G(X DRCD2(XDRF L,XDRCD2,. 01
	11314	,"I"))
	11315	;
	11316	INIT1S DPT DNL=$P(DPT DN,","),DP TDNF=$P($P (DPTDN,"," ,2)," "),D PTDNFI=$E( DPTDNF)
	11317	,DPTDNM=$P ($P(DPTDN, ",",2)," " ,2),DPTDNM I=$E(DPTDN M)
	11318	;
	11319	INIT2S DPT DNL2=$P(DP TDN2,","), DPTDNF2=$P ($P(DPTDN2 ,",",2)," "),DPTDNFI 2=$E(DP
	11320	TDNF2),DPT DNM2=$P($P (DPTDN2,", ",2)," ",2 ),DPTDNMI2 =$E(DPTDNM 2)
	11321	Q
	11322	;
	11323	NAME;
	11324	D COMPARE
	11325	D:$O(^DPT( XDRCD2,.01 ,0)) OTHER 2
	11326	Q
	11327	;
	11328	OTHER;
	11329	F DPTDNO=0 :0 S DPTDN O=$O(^DPT( XDRCD,.01, DPTDNO)) Q :'DPTDNO S DPTDN=$P (^
	11330	DPT(XDRCD, .01,DPTDNO ,0),U,1) S :'$D(DPTDN 2) DPTDN2= XDRCD2(XDR FL,XDRCD2, .01,"I") D INIT1,NAM E
	11331	Q
	11332	;
	11333	OTHER2;
	11334	F DPTDNO2= 0:0 S DPTD NO2=$O(^DP T(XDRCD2,. 01,DPTDNO2 )) Q:'DPTD NO2 S DPT DN
	11335	2=$P(^DPT( XDRCD2,.01 ,DPTDNO2,0 ),U,1) D I NIT2,COMPA RE
	11336	Q
	11337	;
	11338	COMPARE;
	11339	S:'$D(DPTD N("TEST SC ORE")) DPT DN("TEST S CORE")=DPT DN("NO MAT CH")
	11340	I DPTDN=DP TDN2 S DPT DN("TEST S CORE2")=DP TDN("MATCH ") G COMPA REX
	11341
	11342	I DP TDNF=DPTDN F2,DPTDNL= DPTDNL2 S DPTDN("TES T SCORE2") =DPTDN("MA TCH")*.8
	11343	G COMPAR EX
	11344	I DPTDNFI= DPTDNFI2,D PTDNL=DPTD NL2 S DPTD N("TEST SC ORE2")=DPT DN("MATCH" )*
	11345	.6 G COMPA REX
	11346	I DPTDNL=D PTDNL2 S D PTDN("TEST SCORE2")= DPTDN("MAT CH")*.4 G COMPAREX
	11347	S X=DPTDNL D SOU^DIC M1 S DPTDN LS=X S X=D PTDNL2 D S OU^DICM1 S DPTDNL2S= X
	11348	S X=DPTDNF D SOU^DIC M1 S DPTDN FS=X S X=D PTDNF2 D S OU^DICM1 S DPTDNF2S= X
	11349	I DPTDNLS= DPTDNL2S,D PTDNFS=DPT DNF2S S DP TDN("TEST SCORE2")=D PTDN("MATC H"
	11350	)*.6 G COM PAREX
	11351	I DPTDNFS= DPTDNF2S S DPTDN("TE ST SCORE2" )=DPTDN("M ATCH")*.2 G COMPAREX
	11352	S DPTDN("T EST SCORE2 ")=DPTDN(" NO MATCH")
	11353	COMPAREX;
	11354	S:DPTDN("T EST SCORE2 ")>(DPTDN( "TEST SCOR E")) DPTDN ("TEST SCO RE")=DPTDN ("
	11355	TEST SCORE 2")
	11356	K X,DPTDNL S,DPTDNL2S ,DPTDNFS,D PTDNF2S,DP TDN("TEST SCORE2")
	11357	Q
	11358	;
	11359	EOJ;
	11360	S:$D(DPTDN ("TEST SCO RE")) XDRD ("TEST SCO RE")=DPTDN ("TEST SCO RE")
	11361	K DPTDN,DP TDN2,DPTDN F,DPTDNF2, DPTDNL,DPT DNL2,DPTDN M,DPTDNM2
	11362	K DPTDNMI, DPTDNMI2,D PTDNFI,DPT DNFI2,DPTD NO,DPTDNO2
	11363	Q
	11364
	11365	Date of Bi rth test R outine for a Patient Merge Exa mple
	11366	Figure 119 : Special Processing Routine E xamples—Da te of Birt h test Rou tine for a Patient M erge
	11367	DPTDOB;IHS /OHPRD/JCM ;COMPARES DATE OF BI RTHS; [ 06 /08/92 12 :10 PM ]
	11368	;;1.0;DPTD ;;AUG 13, 1991
	11369	START;
	11370	D INIT
	11371	EN; EP - E ntry point for compa ring dates
	11372	D COMPARE
	11373	ENDD EOJ
	11374	Q
	11375	;
	11376	INIT;
	11377	K DPTDOB,D PTDOB2
	11378	S DPTDOB=$ G(XDRCD(XD RFL,XDRCD, .03,"I")), DPTDOB2=$G (XDRCD2(XD RFL,XDRCD2 ,.
	11379	03,"I"))
	11380	S DPTDOB(" MATCH")=$P (XDRDTEST( XDRDTO),U, 6)
	11381	S DPTDOB(" NO MATCH") =$P(XDRDTE ST(XDRDTO) ,U,7)
	11382	Q
	11383	;
	11384	COMPARE;
	11385	I DPTDOB'] ""!(DPTDOB 2']"") G C OMPAREX
	11386	I DPTDOB=D PTDOB2 S X DRD("TEST SCORE")=DP TDOB("MATC H") G COMP AREX
	11387	S DPTDOB(" CNT")=0
	11388	F DPTDOBI= 1:1:7 Q:DP TDOB("CNT" )>2 I $E( DPTDOB,DPT DOBI)'=$E( DPTDOB2,DP TD
	11389	OBI) S DPT DOB("CNT") =DPTDOB("C NT")+1
	11390	K DPTDOBI
	11391	S XDRD("TE ST SCORE") =$S(DPTDOB ("CNT")>2: DPTDOB("NO MATCH"),1 :(DPTDOB(" MA
	11392	TCH")*.8))
	11393	COMPAREX Q
	11394	;
	11395	EOJ;
	11396	K DPTDOB,D PTDOB2
	11397	Q
	11398
	11399	Applicatio n Programm ing Interf aces (APIs )
	11400	EN^XDRMERG (): Merge File Entri es
	11401	Reference Type:Suppo rted
	11402	Category:T oolkit—Dup licate Rec ord Merge
	11403	ICR #:2365
	11404	Descriptio n:This API provides for mergin g of one o r more pai rs of reco rds in a s pecified f ile. This entry poin t takes tw o (2) argu ments, the file numb er (a nume ric value) and a clo sed refere nce to the location where the program fi nds an arr ay with su bscripts i ndicating the record pairs to be merged (a text va lue).
	11405	Format:EN^ XDRMERG(fi le,arrayna m)
	11406	Input Para meters:fil e:(require d) Specifi es the FIL E NUMBER o f the file in which the indica ted entrie s are to b e merged.
	11407	Input/Outp ut
	11408	Parameter: arraynam:( required) This param eter conta ins the na me of the array as a closed ro ot under w hich the s ubscripts indicating the FROM and TO ent ries are f ound. The data can h ave either two or fo ur subscri pts descen dent from the array, which is passed.
	11409	REF: For e xamples of its usage , see the “Overview” section.
	11410
	11411	Examples
	11412	The follow ing comman d would re sult in re cord pairs specified as subscr ipts in th e array MY LOC to be merged in a hypothet ical file #999000014 :
	11413	D EN^XDRME RG(9990000 14,“MYLOC” )
	11414	The array MYLOC migh t have bee n set up p rior to th is call in the follo wing manne r (or any equivalent way) wher e the subs cripts rep resent the internal entry numb ers of the FROM and TO records , respecti vely.
	11415	S MYLOC(14 7,286)=“”, MYLOC(182, 347)=“”,MY LOC(2047,1 92)=“”
	11416	S MYLOC(83 7,492)=“”, MYLOC(298, 299)=“”
	11417	This would result in five reco rd pairs b eing merge d with rec ord 147 (t he FROM re cord) bein g merged i nto record 286 (the TO record) , record 1 82 being m erged into record 34 7, etc., t o record 2 98 being m erged into 299. Merg es using t he two sub script for mat occurs without a specific record of the entrie s prior to the merge (The inte rnal entry numbers m erged woul d be recor ded under the file n umber in X DR REPOINT ED ENTRY f ile [#15.3 ]) An alte rnative is a four su bscript fo rmat for t he data ar ray that u ses variab le pointer formats f or the FRO M and TO r ecords as the third and fourth subscript s. If the merge is p erformed w ith this f our subscr ipt array, then a pr e-merge im age of the data of b oth the FR OM and TO records in the prima ry file an d all othe r merged f iles (thos e related by DINUM) and inform ation on a ll single value poin ter values modified is stored in the MER GE IMAGE f ile (#15.4 ).
	11418	For the sa mple data above [ass uming that the globa l root for the hypot hetical fi le #999000 014 is ^DI Z(99900001 4,] the fo ur subscri pt array m ight be ge nerated us ing the fo llowing co de:
	11419	S MYROOT=“ ;DIZ(99900 014,” <-- - note the leading ^ is omitte d
	11420	S MYLOC(14 7,286,147_ MYROOT,286 _MYROOT)=“ ”
	11421	S MYLOC(18 2,347,182_ MYROOT,347 _MYROOT)=“ ”
	11422	S MYLOC(20 47,192,204 7_MYROOT,1 92_MYROOT) =“”
	11423	S MYLOC(83 7,492,837_ MYROOT,492 _MYROOT)=“ ”
	11424	S MYLOC(29 8,299,298_ MYROOT,299 _MYROOT)=“ ”
	11425	;
	11426	D EN^XDRME RG(9990001 4,“MYLOC”)
	11427	Exclusion of Multipl e Pairs Fo r a Record —To insure that ther e are no u nanticipat ed problem s due to r elationshi ps between a specifi c record i n multiple merges, p rior to ac tually mer ging any d ata the va rious FROM and TO re cords incl uded in th e process are examin ed, and if one recor d is invol ved in mor e than one merge, al l except t he first p air of rec ords invol ving that one are ex cluded fro m the merg e. If any pairs are excluded f or this re ason, a ma il message is genera ted to the individua l responsi ble for th e merge pr ocess as i ndicated b y the DUZ.
	11428	If the fol lowing ent ries were included i n the MYLO C array:
	11429	MYLOC(128, 247)
	11430	MYLOC(128, 536) and
	11431	MYLOC(247, 128)
	11432	Only the f irst of th ese entrie s (based o n the nume ric sortin g of the a rray) woul d be permi tted to re main in th e merge pr ocess, whi le the oth er two pai rs would b e omitted) . And alth ough it ma y seem unl ikely that someone w ould indic ate that a record sh ould be me rged into two differ ent locati ons, while another l ocation sh ould be me rged into one that w as merged away, if t he pairs a re selecte d automati cally and checks are not inclu ded to pro hibit such behavior, they show up. That is why the merge pro cess does not includ e more tha n one pair with a sp ecific rec ord in it.
	11433	Problems R elated To Data Entry While Mer ging
	11434	The Merge Process ha s been des igned to c ombine dat a associat ed with th e two reco rds in the manner de scribed ab ove. On oc casion, ho wever, the re are pro blems that cause VA FileMan to reject th e data tha t is being entered. This may h appen for a number o f reasons. Some exam ples that have been observed i nclude:
	11435	Clinics th at had bee n changed so they no longer we re indicat ed as Clin ics (so th ey would n ot add to the number that peop le had to browse thr ough to se lect a cli nic), but were rejec ted since the input transform checked th at they be clinics.
	11436	Pointer va lues that no longer had a vali d value in the point ed to file (dangling pointers) .
	11437	Fields tha t have inp ut transfo rms that p rohibit da ta entry.
	11438	It is poss ible to us e a validi ty checker on your d ata prior to initiat ing the ac tual merge process ( this is th e action t aken by me rges worki ng from th e Potentia l Duplicat e file). T he data pa irs are pr ocessed in a manner similar to the actua l merge, s o only tha t data in any of the files tha t would be merged an d for whic h the data would be entered us ing VA Fil eMan utili ties for t he specifi c pair are checked t o insure t hey pass t he input t ransform. Any proble ms noted a re incorpo rated into a mail me ssage for resolution prior to attempting to merge the pair a gain, and the pair i s removed from the d ata array that was p assed in. Pairs that pass thro ugh this c hecking sh ould not e ncounter a ny data pr oblems whi le being m erged.
	11439	RESTART^XD RMERG(): R estart Mer ge
	11440	Reference Type:Suppo rted
	11441	Category:T oolkit—Dup licate Rec ord Merge
	11442	ICR #:2365
	11443	Descriptio n:This API restarts a merge th at has bee n stopped. The infor mation nec essary for restartin g can be v iewed usin g the CHKL OCAL^XDRME RG2 API (s ee LOCAL M ERGE STATU S).
	11444	Format:RES TART^XDRME RG(file,ar raynam,pha se,currfil e,currien)
	11445	Input Para meters:fil e:(require d) Specifi es the FIL E NUMBER o f the file in which the indica ted entrie s are to b e merged.
	11446	arraynam:( required) This param eter conta ins the na me of the array as a closed ro ot under w hich the s ubscripts indicating the FROM and TO ent ries are f ound. The data can h ave either two or fo ur subscri pts descen dent from the array, which is passed.
	11447	REF: For e xamples of its usage , see the overall de scription provided.
	11448	phase:(req uired) Thi s variable indicates the phase of the me rge proces s in which the merge should be restarted . The valu e is a num ber in the range of 1 to 3, wi th no deci mal places . Phase 1 is usually quite sho rt and is the merge of the spe cified ent ries in th e primary file. Phas e 2 is the merging o f entries in files t hat are DI NUMed to t he primary file and changing p ointers th at can be identified from cros s-referenc es. Phase 3 is findi ng pointer values by searching each entr y in a fil e. This is usually t he longest phase of the merge process.
	11449	currfile:( required) This is th e current file NUMBE R on which the merge process i s operatin g.
	11450	currien:(r equired) T his is the current i nternal en try number in the fi le on whic h the merg e process is operati ng.
	11451	Output:non e.
	11452
	11453	SAVEMERG^X DRMERGB(): Save Imag e of Exist ing and Me rged Data
	11454	Reference Type:Contr olled Subs cription
	11455	Category:T oolkit—Dup licate Rec ord Merge
	11456	ICR #:2338
	11457	Descriptio n:During s pecial pro cessing re lated to t he Patient Merge, th e routine IBAXDR nee ds to call the entry point SAV EMERG^XDRM ERGB. This API saves the file image of a n entry in volved in the merge process wh en only on e of the e ntries (th e entry be ing merged or the en try being merged int o) is pres ent in [FI LENUM]. No rmally, th e merge pr ocess woul d handle w hen it can identify a FROM or a TO entry that is n ot present based on the DINUMe d values. For [FILEN UM], howev er, the in ternal ent ry numbers are deter mined from the “B”-c ross- refe rence, and missing e ntries nee d to be ha ndled sepa rately.
	11458	This API a cts to sav e an image of the cu rrently ex isting dat a for the merge entr y and merg ed into en try in the MERGE IMA GE file (# 15.4).
	11459	Format:SAV EMERG^XDRM ERGB([file num],ienfr om,iento)
	11460	Input Para meters:fil enum:(requ ired) This is the fi le number for the fi le that is being mer ged and fo r which th e images a re to be s aved.
	11461	ienfrom:(r equired) T he interna l entry nu mber of th e FROM ent ry (the en try being merged int o another entry).
	11462	iento:(opt ional) The internal entry numb er of the TO entry ( the entry into which the entry is being merged).
	11463	Output:res ults:Store d image.
	11464
	11465	Toolkit—HT TP Client
	11466	Overview
	11467	The Kernel Toolkit H ypertext T ransfer Pr otocol (HT TP) Client Helper so ftware rel ease adds a new tool in a set of Infrast ructure so ftware too ls that de velopers c an use. HT TP is a fa st and rel iable way for an app lication t o collect data from another so urce. Kern el Toolkit patch XT* 7.3*123 al lows VistA to t into this info rmation an d retrieve Web data.
	11468	NOTE: Kern el Toolkit patch XT* 7.3*138 ad ds support for IPv6, HTTP/1.1, and HTTPS .
	11469	This code was origin ally devel oped by an other Vist A applicat ion that h ad a press ing need f or this ca pability. The Kernel Toolkit d evelopment team is p roviding a nd maintai ning it as generic t ool so tha t other de velopers m ay use its functiona lity for t heir needs . For exam ple:
	11470	KIDS: Uses it to get the check sums from FORUM of p atches tha t are sent in a Host File Syst em (HFS) f ile.
	11471	Pharmacy: Uses it to request t he printin g of FDA d ata sheets .
	11472	NOTE: XTHC * routines are part of the HTT P Client H elper appl ication fo r develope rs.
	11473	Applicatio n Programm ing Interf aces (APIs )
	11474	$$GETURL^X THC10: Ret urn URL Da ta Using H TTP
	11475	Reference Type:Suppo rted
	11476	Category:T oolkit—HTT P Client H elper
	11477	ICR #:5553
	11478	Descriptio n:This ext rinsic fun ction is a Hypertext Transfer Protocol ( HTTP)/1.1 client tha t can requ est a web page from another sy stem and p ass the re turned dat a to the c alling rou tine.
	11479	It can mak e both GET and POST requests.
	11480	It is the main API a nd returns in xt8rda t the retu rned data from the w ebsite.
	11481	This API w as release d with Ker nel Toolki t patch XT 7.3123.
	11482	NOTE: XTHC * routines are part of the HTT P Client H elper appl ication fo r develope rs.
	11483	NOTE: This API is IP v6 complia nt as of K ernel Tool kit patch XT7.3138 .
	11484	Format:
	11485	$$GETURL^X THC10(url[ ,xt8flg],x t8rdat,.xt 8rhdr[,xt8 sdat][,.xt 8shdr][,.x t8meth])
	11486	Input Para meters:url :(required ) This is the Univer sal Resour ce Locator (URL) to access (ht tp://host: port/path) . It could be as sim ple as "ww w. DOMAIN ".
	11487	xt8flg:(op tional) Re quest time out. Defau lt is 5 se conds.
	11488	xt8sdat:(o ptional) C losed root of a vari able conta ining the body of th e request message. D ata should be format ted as des cribed in the xt8rda t paramete r.
	11489	NOTE: If t his parame ter is def ined (i.e. , not empt y) and the reference d array co ntains dat a, then th e POST req uest is ge nerated; o therwise, the GET re quest is s ent.
	11490	.xt8shdr:( optional) Reference to a local variable containing header va lues, whic h is added to the re quest. For example:
	11491	XT8SHDR("C ONTENT-TYP E")="text/ html"
	11492	.xt8meth:( optional) Flag to in dicate the request m ethod:
	11493	"GET"—Defa ult if xt8 sdat conta ins no dat a.
	11494	"POST"—Def ault if xt 8sdat cont ains data.
	11495	"HEAD"
	11496	"PUT"
	11497	"OPTIONS"
	11498	"DELETE"
	11499	"TRACE"
	11500	Output / O utput
	11501	Parameters :xt8rdat:( required) Closed roo t of the v ariable wh ere the me ssage body is return ed. Data i s stored i n consecut ive nodes (numbers s tarting fr om 1). If a line is longer tha n 245 char acters, on ly 245 cha racters ar e stored i n the corr esponding node. Afte r that, ov erflow sub -nodes are created. For exampl e:
	11502	@XT8DATA@( 1)="<html> " @XT8DATA @(2)="<hea d><title>V istA</titl e></head>" @XT8DATA@ (3)="<body >" @XT8DAT A@(4)="<p> " @XT8DATA @(5)="Begi nning of a very long line" @X T8DATA@(5, 1)="Contin uation #1 of the lon g line" @ XT8DATA@(5 ,2)="Conti nuation #2 of the lo ng line" @XT8DATA@( 5,...)=... @XT8DATA@ (6)="</p>"
	11503	.xt8rhdr: (required) Reference to a loca l variable where the parsed he aders are returned. Header nam es are con verted to uppercase; the value s are left "as is". The root n ode contai ns the sta tus line. For exampl e:
	11504	XT8HDR="HT TP/1.1 200 OK" XT8HD R("ACCEPT- RANGES")=" bytes" XT8 HDR("CONNE CTION")="c lose" XT8H DR("CONTEN T-LENGTH") ="16402" X T8HDR("CON TENT-TYPE" )="text/ht ml; charse t=UTF-8" X T8HDR("DAT E")="Thu, 25 Jun 201 5 14:43:01 GMT" XT8H DR("ETAG") ="a93a2-40 12-5180156 550680" XT 8HDR("LAST -MODIFIED" )="Mon, 08 Jun 2015 13:08:26 G MT" XT8HDR ("SERVER") ="Apache/2 .2.15 (Cen tOS)"
	11505	Output:ret urns:Retur ns:
	11506	Success: H TTP_Status _Code^Desc ription Co mmon HTTP status cod es returne d:
	11507	Table 32: $$GETURL^X THC10—Comm on HTTP St atus Codes Returned
	11508	Status Cod e
	11509	Descriptio n
	11510	200
	11511	OK
	11512	301
	11513	Moved Perm anently
	11514	400
	11515	Bad Reques t
	11516	401
	11517	Unauthoriz ed
	11518	404
	11519	Not Found
	11520	407
	11521	Proxy Auth entication Required
	11522	408
	11523	Request Ti me-out
	11524	500
	11525	Internal S erver Erro r
	11526	505
	11527	HTTP Versi on not sup ported
	11528
	11529	Fail: -1^E rror Descr iptor (add itional er ror inform ation can be found i n the Vist A error tr ap or ^XTE R in progr ammer mode )
	11530	REF: For m ore detail s, visit t he HTTP Fr equently A sked Quest ions (FAQ) website a t: http:// www.faqs.o rg/rfcs/rf c1945.html or the In ternet Eng ineering T ask Force (IETF) sit es at: htt p://www.ie tf.org/rfc /rfc2616.t xt (HTTP/1 .1) and ht tp://www.i etf.org/rf c/rfc2617. txt (HTTP Authentica tion).
	11531
	11532	$$ENCODE^X THCURL: En codes a Qu ery String
	11533	Reference Type:Suppo rted
	11534	Category:T oolkit—HTT P Client H elper
	11535	ICR #:5554
	11536	Descriptio n:This ext rinsic fun ction enco des the qu ery string . The $$MA KEURL^XTHC URL: Creat es a URL f rom Compon ents API u ses this e xtrinsic f unction.
	11537	This API w as introdu ced with K ernel Tool kit patch XT7.3123 .
	11538	NOTE: XTHC * routines are part of the HTT P Client H elper appl ication fo r develope rs.
	11539	Format:$$E NCODEURL^X THCURL(str )
	11540	Input Para meters:str :(required ) String o f data to be encoded .
	11541	Output:ret urns:Retur ns:
	11542	Success: E ncoded que ry string.
	11543	Fail: -1^S tring not defined (i f missing str parame ter).
	11544
	11545	Example
	11546	W $$ENCODE ^XTHCURL(“ 123+main+s t.,Anycity ,CA”)
	11547	123%2Bmain %2Bst.%2CA nycity%2CC A
	11548
	11549	$$MAKEURL^ XTHCURL: C reates a U RL from Co mponents
	11550	Reference Type:Suppo rted
	11551	Category:T oolkit—HTT P Client H elper
	11552	ICR #:5554
	11553	Descriptio n:This ext rinsic fun ction crea tes a URL from compo nents.
	11554	This API w as introdu ced with K ernel Tool kit patch XT7.3123 .
	11555	NOTE:XTHC* routines are part o f the HTTP Client He lper appli cation for developer s.
	11556	NOTE: This API is IP v6 complia nt as of K ernel Tool kit patch XT7.3138 .
	11557
	11558	Format:$$M AKEURL^XTH CURL(host[ ,port][,pa th][,.quer y])
	11559	Input Para meters:hos t:(require d) The Ful ly Qualifi ed Domain Name (FQDN ) or Inter net Protoc ol (IP) ad dress of t he system to which i t connects .
	11560	port:(opti onal) The port to us e. Default is port 8 0 for http or port 4 43 for htt ps.
	11561	path:(opti onal) The path to th e web page on the ca lled serve r.
	11562	.query:(op tional) An array of query para meters.
	11563	Output:ret urns:Retur ns:
	11564	Success: N ormalized path (see Example).
	11565	Fail: -1^H ost not de fined (if missing ho st paramet er).
	11566
	11567	Example
	11568	Figure 120 : $$MAKEUR L^XTHCURL API—Exampl e
	11569	S host="ht tp://www.m ap.com"
	11570	S path="ap i/staticma p"
	11571	S query("c enter")="m ain+st.,An ycity,CA"
	11572	S query("s ensor")="f alse"
	11573	W $$MAKEUR L^XTHCURL( host,,path ,.query)
	11574
	11575	http://www .map.com/a pi/staticm ap?center= main%2Bst. %2CAnycity %2CCA&sens or=false
	11576
	11577	$$PARSEURL ^XTHCURL: Parses a U RL
	11578	Reference Type:Suppo rted
	11579	Category:T oolkit—HTT P Client H elper
	11580	ICR #:5554
	11581	Descriptio n:This ext rinsic fun ction pars es a URL u sing into host, port , and path (path inc ludes quer y string).
	11582	This API w as introdu ced with K ernel Tool kit patch XT7.3123 .
	11583	NOTE:XTHC* routines are part o f the HTTP Client He lper appli cation for developer s.
	11584	NOTE: This API is IP v6 complia nt as of K ernel Tool kit patch XT7.3138 .
	11585	Format:$$P ARSEURL^XT HCURL(url, .host,.por t,.path)
	11586	Input Para meters:url :(required ) Referenc e to varia ble where host name is to be r eturned.
	11587	Output Par ameters:ho st:(requir ed) Input URL.
	11588	port:(requ ired) Refe rence to v ariable wh ere port i s to be re turned.
	11589	.path:(req uired) Ref erence to variable w here path string is to be retu rned.
	11590	Output:ret urns:Retur ns:
	11591	Success: 0 .
	11592	Fail: -1^E rror Descr iption.
	11593
	11594	Example
	11595	D PARSEURL ^XTHCURL(“ http://cgi .vagroup. DOMAIN :9999/tpl/ PKG”,.ZH,. ZP,.ZA)
	11596	W ZH,!,ZP, !,ZA
	11597
	11598	vagroup. DOMAIN
	11599	9999
	11600	/tpl/PKG
	11601
	11602	$$DECODE^X THCUTL: De codes a St ring
	11603	Reference Type:Suppo rted
	11604	Category:T oolkit—HTT P Client H elper
	11605	ICR #:5555
	11606	Descriptio n:This ext rinsic fun ction is u sed with t he HTTP/1. 1 Client. It decodes one strin g replacin g the foll owing:
	11607	< with <
	11608	> with >
	11609	& with &
	11610	wit h “ “
	11611	&os; with ‘
	11612	" wit h “
	11613	A with A
	11614	This API w as introdu ced with K ernel Tool kit patch XT7.3123 .
	11615	NOTE:XTHC* routines are part o f the HTTP Client He lper appli cation for developer s.
	11616	Format:$$D ECODE^XTHC UTL(str)
	11617	Input Para meters:str :(required ) String t o be decod ed.
	11618	Output:ret urns:Retur ns:
	11619	Success: D ecoded str ing.
	11620	Fail: -1^S tring not defined (i f missing str parame ter).
	11621
	11622	Example
	11623	$$DECODE^X THCUTL("12 3%2Bmain%2 Bst.%2CAny town%2CCA" )
	11624	123%2Bmai n%2Bst.%2C Anytown%2C CA
	11625
	11626	Toolkit—KE RMIT APIs
	11627	RFILE^XTKE RM4: Add E ntries to Kermit Hol ding File
	11628	Reference Type:Suppo rted
	11629	Category:T oolkit—KER MIT
	11630	ICR #:2075
	11631	Descriptio n:This API allows ac cess to th e KERMIT H OLDING fil e (#8980) and the AP I that add s entries to it, RFI LE^XTKERM4 . The “AOK ” cross-re ference of the KERMI T HOLDING file (#898 0) can be checked to see if th e user has an entry in the KER MIT HOLDIN G file (#8 980). If n ot, RFILE^ XTKERM4 ca n be calle d to add a n entry to the file.
	11632	NOTE: A ca ll to RFIL E^XTKERM4 allows a u ser to add or select an entry in the KER MIT HOLDIN G file (#8 980).
	11633	Format:RFI LE^XTKERM4
	11634	Make sure to perform the follo wing steps before ca lling this API:
	11635	NEW all no n-namespac ed variabl es.
	11636	Set all in put variab les.
	11637	Call the A PI.
	11638	Output Var iables:XTK DIC:This v ariable re turns the global roo t and is a calling v ariable us ed by call s to RECEI VE^XTKERMI T: Load a File into the Host o r SEND^XTK ERMIT: Sen d Data fro m Host API s.
	11639	XTMODE:Thi s variable is return ed. It is used as in put to cal ls to RECE IVE^XTKERM IT: Load a File into the Host or SEND^XT KERMIT: Se nd Data fr om Host AP Is.
	11640
	11641	RECEIVE^XT KERMIT: Lo ad a File into the H ost
	11642	Reference Type:Suppo rted
	11643	Category:T oolkit—KER MIT
	11644	ICR #:1009 5
	11645	Descriptio n:The API loads a fi le into th e host.
	11646	Format:REC EIVE^XTKER MIT
	11647	Make sure to perform the follo wing steps before ca lling this API:
	11648	NEW all no n-namespac ed variabl es.
	11649	Set all in put variab les.
	11650	Call the A PI.
	11651	Variables to call
	11652	from outsi de of
	11653	KERMIT:XTK DIC:(requi red) Set X TKDIC to V A FileMan type globa l root.
	11654	DWLC:(requ ired) Set DWLC to la st current data node .
	11655	Return DWL C to last data node, XTKDIC is KILLed.
	11656	TIREF:(opt ional) Set XTKMODE a s follows to send/re ceive:
	11657	0—Send/Rec eive in IM AGE mode ( no convers ion).
	11658	1—Send/Rec eive in DA TA mode (j ust conver t control character) .
	11659	2—Send/Rec eive as TE XT (VA Fil eMan word- processing ). Text mo de sends a carriage return (CR ) after ea ch global node; make s a new gl obal node for each C R received . XTKMODE set to 2 w ould be no rmal for m ost VistA applicatio ns.
	11660
	11661	SEND^XTKER MIT: Send Data from Host
	11662	Reference Type:Suppo rted
	11663	Category:T oolkit—KER MIT
	11664	ICR #:1009 5
	11665	Descriptio n:The API sends data from host .
	11666	Format:SEN D^XTKERMIT
	11667	Make sure to perform the follo wing steps before ca lling this API:
	11668	NEW all no n-namespac ed variabl es.
	11669	Set all in put variab les.
	11670	Call the A PI.
	11671	Variables to call
	11672	from outsi de of
	11673	KERMIT:XTK DIC:(requi red) Set X TKDIC to V A FileMan type globa l root.
	11674	DWLC:(requ ired) Set DWLC to la st current data node .
	11675	Return DWL C to last data node, XTKDIC is KILLed.
	11676	TIREF:(opt ional) Set XTKMODE a s follows to send/re ceive:
	11677	0—Send/Rec eive in IM AGE mode ( no convers ion).
	11678	1—Send/Rec eive in DA TA mode (j ust conver t control character) .
	11679	2—Send/Rec eive as TE XT (VA Fil eMan word- processing ). Text mo de sends a carriage return (CR ) after ea ch global node; make s a new gl obal node for each C R received . XTKMODE set to 2 w ould be no rmal for m ost VistA applicatio ns.
	11680
	11681	Toolkit—Mu lti-Term L ook-Up (MT LU) APIs
	11682	How to Ove rride
	11683	If files a re fully c onfigured for the sp ecial Mult i-Term Loo k-Up, all standard V A FileMan lookups in voke MTLU. The follo wing proce dures can be taken t o override MTLU:
	11684	Users can enter an a ccent grav e (`) as a prefix to request a lookup by the Inter nal Entry Number (IE N).
	11685	Users can enter a ti lde (~) as a prefix to force a standard VA FileMan lookup.
	11686	NOTE: In t he event t hat a sear ch produce s no match es, MTLU c ontinues w ith a stan dard VA Fi leMan sear ch by defa ult.
	11687	Developers can overr ide MTLU b y setting the variab le XTLKUT= “” prior t o referenc ing the fi le and KIL Ling it up on exit, o r set DIC( 0) to incl ude “I”:
	11688	S DIC=81,D IC(0)=“AEM QI”,X=“” D ^DIC
	11689	Applicatio n Programm ing Interf aces (APIs )
	11690	MTLU and V A FileMan Supported Calls
	11691	Developers can perfo rm any sup ported VA FileMan ca lls on fil es fully c onfigured for MTLU.
	11692	The prefer red method of perfor ming looku ps from Pr ogrammer m ode is to add the ta rget file to the LOC AL LOOKUP file (#898 4.4) and c all LKUP^X TLKMGR. Ho wever, Mul ti-Term Lo ok-Ups can be perfor med on any VA FileMa n file, ev en if it h as not bee n configur ed for use by MTLU. Using the developer API, the l ookup can be perform ed using a ny index c ontained w ithin the file, such as a VA F ileMan KWI C cross-re ference.
	11693	Entry Poin t:XTLKKWL
	11694	Required I nput
	11695	Parameters :(XTLKGBL, XTLKKSCH( “GBL”)):Th is is the global roo t (same as DIC).
	11696	XTLKKSCH(“ DSPLY”):Th is variabl e displays the routi ne. For ex ample:
	11697	DGEN^XTLKK WLD
	11698	XTLKKSCH(“ INDEX”):Cr oss-refere nce select ed by the developer for perfor ming a mul ti-term lo okup.
	11699	XTLKX:This is the us er input.
	11700	Optional I nput
	11701	Variables: XTLKSAY:Th is variabl e equals 1 or 0. If XTLKSAY = 1, MTLU di splays det ails durin g the look up.
	11702	NOTE: The purpose of XTLKSAY i s to contr ol the deg ree of out put to the screen, n ot the amo unt of “fi le informa tion” disp layed.
	11703	XTLKHLP:Ex ecutable c ode to dis play custo m help.
	11704
	11705	Kernel Too lkit Enhan ced APIs
	11706	Programmer calls to MTLU-confi gured file s return a ll standar d VA FileM an variabl es (i.e., Y, DTOUT, DUOUT, DIR OUT, and D IRUT).
	11707	The progra mmer’s API for perfo rming a lo okup has b een enhanc ed functio nally, sim plified, a nd convert ed to a pr ocedure ca ll.
	11708	Procedure calls prov ide full, non-intera ctive mana gement of the follow ing MTLU c ontrol fil es: LOCAL KEYWORD (# 8984.1), L OCAL SHORT CUT (#8984 .2), LOCAL SYNONYM ( #8984.3), and LOCAL LOOKUP (#8 984.4).
	11709	All proced ure calls are contai ned in the routine ^ XTLKMGR.
	11710	Errors are returned in the XTL KER() arra y. KILL th is array b efore call ing any of these new procedure calls, an d check th e array af ter return ing from t he calls. All calls require th at the tar get file b e defined in the LOC AL LOOKUP file (#898 4.4). If r emoving an entry fro m the LOCA L LOOKUP f ile (#8984 .4), all s hortcuts, synonyms, and keywor ds associa ted with t hat file m ust be del eted first .
	11711	XTLKKWL^XT LKKWL: Per form Suppo rted VA Fi leMan Call s on Files Configure d for MTLU
	11712	Reference Type:Suppo rted
	11713	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11714	ICR #:1012 2
	11715	Descriptio n:This API lets deve lopers per form any s upported V A FileMan calls on f iles confi gured for MTLU. To i gnore the special lo okup routi ne, XTLKDI CL, be sur e that DIC (0) includ es an “I.” Alternati vely, mult i-term loo kups can b e performe d on any V A FileMan file, even if it has not been configured for prima ry use by MTLU. Usin g the prog rammer API , the look up can be performed using any index cont ained with in the fil e, such as a VA File Man Key Wo rd In Cont ext (KWIC) cross-ref erence.
	11716	Format:XTL KKWL^XTLKK WL
	11717	Make sure to perform the follo wing steps before ca lling this API:
	11718	NEW all no n-namespac ed variabl es.
	11719	Set all in put variab les.
	11720	Call the A PI.
	11721	Input Vari ables:(XTL KGBL, XTLK KSCH(“GBL” )):(requir ed) This i s the glob al root (s ame as DIC ).
	11722	XTLKKSCH(“ DSPLY”):(r equired) T his variab le display s the rout ine. For e xample:
	11723	DGEN^XTLKK WLD
	11724	XTLKKSCH(“ INDEX”):(r equired) C ross-refer ence selec ted by the developer for perfo rming a MT LU.
	11725	XTLKX:(req uired) Thi s is the u ser input.
	11726	XTLKSAY:(o ptional) X TLKSAY val ues:
	11727	1—MTLU dis plays deta ils during the looku p.
	11728	0.
	11729	NOTE: The purpose of XTLKSAY v ariable is to contro l the degr ee of outp ut to the screen, no t the amou nt of “fil e informat ion” displ ayed.
	11730	XTLKHLP:(o ptional) X TLKHLP=Exe cutable co de to disp lay custom help.
	11731
	11732	DK^XTLKMGR (): Delete Keywords from the L ocal Keywo rd File
	11733	Reference Type:Suppo rted
	11734	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11735	ICR #:1015 3
	11736	Descriptio n:This API deletes k eywords fr om the LOC AL KEYWORD file (#89 84.1).
	11737	Format:DK^ XTLKMGR(xt lk1,xtlk2)
	11738	Input Para meters:xtl k1:(requir ed) File n ame.
	11739	xtlk2:(req uired) Lea ve this pa rameter un defined to delete al l keywords for a giv en target file or pa ss in an a rray for s elected ke ywords.
	11740	Output:non e.
	11741
	11742	DLL^XTLKMG R(): Delet e an Entry from the Local Look up File
	11743	Reference Type:Suppo rted
	11744	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11745	ICR #:1015 3
	11746	Descriptio n:This API deletes a n entry fr om the LOC AL LOOKUP file (#898 4.4).
	11747	Format:DLL ^XTLKMGR(x tlk1)
	11748	Make sure to perform the follo wing steps before ca lling this API:
	11749	NEW all no n-namespac ed variabl es.
	11750	Set all in put variab les.
	11751	Call the A PI.
	11752	Input Para meters:xtl k1:(requir ed) The as sociated f ile name o r number.
	11753	Output
	11754	Variables: XTLKER(1,F ILENAME):F ile is not in the LO CAL LOOKUP file (#89 84.4).
	11755	XTLKER:Ent ries exist for keywo rds, short cuts, or s ynonyms fo r the asso ciated fil e. These m ust be del eted first .
	11756
	11757	DSH^XTLKMG R(): Delet e Shortcut s from the Local Sho rtcut File
	11758	Reference Type:Suppo rted
	11759	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11760	ICR #:1015 3
	11761	Descriptio n:This API deletes s hortcuts f rom the LO CAL SHORTC UT file (# 8984.2).
	11762	Format:DSH ^XTLKMGR(x tlk1,xtlk2 )
	11763	Input Para meters:xtl k1:(requir ed) File n ame.
	11764	xtlk2:(req uired) Lea ve this pa rameter un defined to delete al l shortcut s for a gi ven target file or p ass in an array for selected s hortcuts.
	11765	Output:non e.
	11766
	11767	DSY^XTLKMG R(): Delet e Synonyms from the Local Syno nym File
	11768	Reference Type:Suppo rted
	11769	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11770	ICR #:1015 3
	11771	Descriptio n:This API deletes s ynonyms fr om the LOC AL SYNONYM file (#89 84.3).
	11772	Format:DSY ^XTLKMGR(x tlk1,xtlk2 )
	11773	Input Para meters:xtl k1:(requir ed) File n ame.
	11774	xtlk2:(req uired) Lea ve this pa rameter un defined to delete al l synonyms for a giv en target file or pa ss in an a rray for s elected sy nonyms.
	11775	Output:non e.
	11776
	11777	K^XTLKMGR( ): Add Key words to t he Local K eyword Fil e
	11778	Reference Type:Suppo rted
	11779	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11780	ICR #:1015 3
	11781	Descriptio n:This API adds Keyw ords to th e LOCAL KE YWORD file (#8984.1) .
	11782	Format:K^X TLKMGR(xtl k1,xtlk2,x tlk3)
	11783	Make sure to perform the follo wing steps before ca lling this API:
	11784	NEW all no n-namespac ed variabl es.
	11785	Set all in put variab les.
	11786	Call the A PI.
	11787	Input Para meters:xtl k1:(requir ed) Associ ated file.
	11788	xtlk2:(req uired) Cod e in the a ssociated file.
	11789	xtlk3:(req uired) Key word.
	11790	Output Var iables:XTL KER(1,FILE NAME):File not defin ed in the LOCAL LOOK UP file (# 8984.4).
	11791	XTLKER(2,C ODE):The c ode is not in the as sociated f ile.
	11792	XTLKER(3,S YNONYM):Th e keyword could not be added.
	11793
	11794	L^XTLKMGR( ): Define a File in the Local Lookup Fil e
	11795	Reference Type:Suppo rted
	11796	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11797	ICR #:1015 3
	11798	Descriptio n:This API defines a file in t he LOCAL L OOKUP file (8984.4). Adding th e target f ile here d oes not au tomaticall y place th e special lookup rou tine, ^XTL KDICL, in the file’s Data Dict ionary. Si nce use of this rout ine is at the discre tion of th e develope r, it shou ld be manu ally added via the E dit File o ption unde r VA FileM an’s Utili ties Menu.
	11799	REF: For i nformation on the Ed it File op tion, see the “Utili ty Functio ns” sectio n in the V A FileMan User Manua l.
	11800	Format:L^X TLKMGR(xtl k1[,xtlk2] ,xtlk3,xtl k4)
	11801	Make sure to perform the follo wing steps before ca lling this API:
	11802	NEW all no n-namespac ed variabl es.
	11803	Set all in put variab les.
	11804	Call the A PI.
	11805	Input Para meters:xtl k1:(requir ed) File n ame or num ber.
	11806	xtlk2:(opt ional) App lication-s pecific di splay prot ocol.
	11807	xtlk3:(req uired) MTL U index to use for l ookups.
	11808	xtlk4:(req uired) Var iable poin ter prefix .
	11809	Output Var iables:XTL KER(1,FILE NAME):File could not be added.
	11810	The follow ing are ex amples (in dex and pr efix can d iffer from actual im plementati on):
	11811	For the IC D DIAGNOSI S file (#8 0):
	11812	>K XTLKER> D L^XTLKMG R(80,“DSPL YD^XTLKKWL D”,“AIHS”, “D”)
	11813	For the IC D OPERATIO N/PROCEDUR E file (#8 0.1):
	11814	>K XTLKER> D L^XTLKMG R(80.1,“DS PLYO^XTLKK WLD”,“KWIC ”,“O”)
	11815
	11816	LKUP^XTLKM GR(): Gene ral Lookup Facility for MTLU
	11817	Reference Type:Suppo rted
	11818	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11819	ICR #:1015 3
	11820	Descriptio n:This API adds term s and syno nyms to th e LOCAL SY NONYM file (#8984.3) .
	11821	Format:LKU P^XTLKMGR( fil,xtlkx[ ,xtlksay][ ,xtlkhlp][ ,xtlkmore] )
	11822	Make sure to perform the follo wing steps before ca lling this API:
	11823	NEW all no n-namespac ed variabl es.
	11824	Set all in put variab les.
	11825	Call the A PI.
	11826	Input Para meters:fil :(required ) Target f ile (must be defined in the LO CAL LOOKUP file (#89 84.4).
	11827	xtlkx:(req uired) Wor d or phras e to use i n lookup.
	11828	xtlksay:(o ptional) - 1, 0, or 1 (default= 1). Set to “0” to mi nimize, “- 1” to prev ent screen display, “1” or “” for full s creen (nor mal) displ ay.
	11829	NOTE: The purpose o f XTLKSAY is to cont rol the de gree of ou tput to th e screen, not the am ount of “f ile inform ation” dis played.If screen dis plays are turned off , MTLU mat ches can b e processe d by check ing the co unt in ^TM P(“XTLKHIT S”,$J). ^T MP(“XTLKHI TS”,$J,cou nt)=IEN of the entry in the ta rget file. ^TMP(“XTL KHITS”) sh ould be ki lled after processin g.
	11830	xtlkhlp:(o ptional) T he lookup was succes sful.
	11831	xtlkmore:( optional) Set to “1” to contin ue with Fi leMan sear ch (defaul t=1).
	11832	Output Var iables:Y=- 1:File not defined i n the LOCA L LOOKUP f ile (#8984 .4).
	11833	Y=N^S:N is the inter nal entry number (IE N) of the entry in t he file an d S is the value of the .01 fi eld for th at entry.
	11834	Y=N^S^1:N and S are defined as above and the 1 ind icates tha t this ent ry has jus t been add ed to the file.
	11835
	11836	Examples
	11837	Example 1
	11838	Figure 121 : LKUP^XTL KMGR API—E xample 1: Standard L ookup; Sin gle term e ntered
	11839	VAH,MTL>D LKUP^XTLKM GR(80,“MAL IG”)
	11840	( MALIG/MA LIGNANT )
	11841	.......... .......... .......... .......... .......... .......... .......... ....
	11842	.......... .......... .......... .......... .......... .......... .......... ....
	11843	.......... .......... .......... .......... ...
	11844
	11845	The follow ing 443 ma tches were found:
	11846
	11847	1: 140. 1 (MAL NEO LOWER VER MILION)
	11848	MAL IGNANT NEO PLASM OF L OWER LIP, VERMILION BORDER
	11849
	11850	2: 140. 3 (MAL NEO UPPER LIP , INNER)
	11851	MAL IGNANT NEO PLASM OF U PPER LIP, INNER ASPE CT
	11852
	11853	3: 140. 4 (MAL NEO LOWER LIP , INNER)
	11854	MAL IGNANT NEO PLASM OF L OWER LIP, INNER ASPE CT
	11855
	11856	4: 140. 5 (MAL NEO LIP, INNE R NOS)
	11857	MAL IGNANT NEO PLASM OF L IP, UNSPEC IFIED, INN ER ASPECT
	11858
	11859	5: 140. 6 (MAL NEO LIP, COMM ISSURE)
	11860	MAL IGNANT NEO PLASM OF C OMMISSURE OF LIP
	11861
	11862	Press <RET > or Selec t 1-5: ^
	11863	...Nothing selected. Attemptin g Fileman lookup.
	11864
	11865	NOTE: Pres sing the < Enter> key continues listing t he MTLU ma tches. If no selecti on is made , MTLU ini tiates a s tandard VA FileMan l ookup (usi ng all ava ilable cro ss-referen ces).
	11866	Example 2
	11867	Figure 122 : LKUP^XTL KMGR API—E xample 2: Standard L ookup; Mul tiple term s entered
	11868	VAH,MTL>D LKUP^XTLKM GR(80,“MAL IGNANCY OF THE LIP”)
	11869
	11870
	11871	(LIP/LIPID OSES/LIPOD YSTROPHY/L IPOID/LIPO MA/LIPOPRO TEIN/LIPOT ROPIC/LIPS MALIGNAN/ MALIGNANT)
	11872
	11873	The follow ing words were not u sed in thi s search:
	11874	OF
	11875	THE
	11876	.......... ..
	11877
	11878	The follow ing 12 mat ches were found:
	11879
	11880	1: 140. 1 (MAL NEO LOWER VER MILION)
	11881	MAL IGNANT NEO PLASM OF L OWER LIP, VERMILION BORDER
	11882
	11883	2: 140. 3 (MAL NEO UPPER LIP , INNER)
	11884	MAL IGNANT NEO PLASM OF U PPER LIP, INNER ASPE CT
	11885
	11886	3: 140. 4 (MAL NEO LOWER LIP , INNER)
	11887	MAL IGNANT NEO PLASM OF L OWER LIP, INNER ASPE CT
	11888
	11889	4: 140. 5 (MAL NEO LIP, INNE R NOS)
	11890	MAL IGNANT NEO PLASM OF L IP, UNSPEC IFIED, INN ER ASPECT
	11891
	11892	5: 140. 6 (MAL NEO LIP, COMM ISSURE)
	11893	MAL IGNANT NEO PLASM OF C OMMISSURE OF LIP
	11894
	11895
	11896	Press <RET > or Selec t 1-5: ^
	11897	...Nothing selected. Attemptin g Fileman lookup. ??
	11898
	11899	Example 3
	11900	Figure 123 : LKUP^XTL KMGR API—E xample 3: Display mi nimized by setting t he 3rd par ameter = 0
	11901	VAH,MTL>S XTLKX=“MAL IGNANCY OF THE LIP”
	11902
	11903	VAH,MTL>D LKUP^XTLKM GR(80,XTLK X,0)
	11904
	11905	The follow ing 12 mat ches were found:
	11906
	11907	1: 140. 1 (MAL NEO LOWER VER MILION)
	11908	MAL IGNANT NEO PLASM OF L OWER LIP, VERMILION BORDER
	11909
	11910	2: 140. 3 (MAL NEO UPPER LIP , INNER)
	11911	MAL IGNANT NEO PLASM OF U PPER LIP, INNER ASPE CT
	11912
	11913	3: 140. 4 (MAL NEO LOWER LIP , INNER)
	11914	MAL IGNANT NEO PLASM OF L OWER LIP, INNER ASPE CT
	11915
	11916	4: 140. 5 (MAL NEO LIP, INNE R NOS)
	11917	MAL IGNANT NEO PLASM OF L IP, UNSPEC IFIED, INN ER ASPECT
	11918
	11919	5: 140. 6 (MAL NEO LIP, COMM ISSURE)
	11920	MAL IGNANT NEO PLASM OF C OMMISSURE OF LIP
	11921
	11922
	11923	Press <RET > or Selec t 1-5: ^ < Enter> ??
	11924	VAH,MTL>
	11925
	11926	Example 4
	11927	Figure 124 : LKUP^XTL KMGR API—E xample 4: MTLU with screen dis play turne d off
	11928	VAH,MTL>D LKUP^XTLKM GR(80,XTLK X,-1)
	11929
	11930
	11931	VAH,MTL>D ^%G
	11932
	11933	Global ^TM P(“XTLKHIT S”,$J
	11934	TM P(“XTLKHIT S”,$J
	11935	^TMP(“XTLK HITS”,5917 95907) = 1 2
	11936	^TMP(“XTLK HITS”,5917 95907,1) = 167
	11937
	11938	NOTE:
	11939
	11940	“167” is t he IEN of the target file.
	11941	^ICD9(167, 0) = 140.1 ^Y^MAL NEO LOWER VER MILION^^3^ ^^^
	11942	^ICD9(167, 1) = MALIG NANT NEOPL ASM OF LOW ER LIP, VE RMILION
	11943	BORDER
	11944	^ICD9(167, “DRG”) = 6 4^^ VERMIL ION^^3^^^^
	11945	NOTE:
	11946
	11947	“167” is t he IEN of the target file.
	11948	^ICD9(167, 0) = 140.1 ^Y^MAL NEO LOWER VER MILION^^3^ ^^^
	11949	^ICD9(167, 1) = MALIG NANT NEOPL ASM OF LOW ER LIP, VE RMILION
	11950	BORDER
	11951	^ICD9(167, “DRG”) = 6 4^^ VERMIL ION^^3^^^^
	11952	^TMP(“XTLK HITS”,5917 95907,2) = 168
	11953	^TMP(“XTLK HITS”,5917 95907,3) = 169
	11954	^TMP(“XTLK HITS”,5917 95907,4) = 170
	11955	^TMP(“XTLK HITS”,5917 95907,5) = 171
	11956	^TMP(“XTLK HITS”,5917 95907,6) = 172
	11957	^TMP(“XTLK HITS”,5917 95907,7) = 173
	11958	^TMP(“XTLK HITS”,5917 95907,8) = 220
	11959	^TMP(“XTLK HITS”,5917 95907,9) = 221
	11960	^TMP(“XTLK HITS”,5917 95907,10) = 8595
	11961	^TMP(“XTLK HITS”,5917 95907,11) = 8623
	11962	^TMP(“XTLK HITS”,5917 95907,12) = 8624
	11963
	11964	SH^XTLKMGR (): Add Sh ortcuts to the Local Shortcut File
	11965	Reference Type:Suppo rted
	11966	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11967	ICR #:1015 3
	11968	Descriptio n:This API adds Shor tcuts to t he LOCAL S HORTCUT fi le (#8984. 2).
	11969	Format:SH^ XTLKMGR(xt lk1,xtlk2, xtlk3)
	11970	Make sure to perform the follo wing steps before ca lling this API:
	11971	NEW all no n-namespac ed variabl es.
	11972	Set all in put variab les.
	11973	Call the A PI.
	11974	Input Para meters:xtl k1:(requir ed) Associ ated file.
	11975	xtlk2:(req uired) Cod e in the a ssociated file.
	11976	xtlk3:(req uired) Sho rtcut (wor d or phras e).
	11977	Output Var iables:XTL KER(1,FILE NAME):File not defin ed in the LOCAL LOOK UP file (# 8984.4).
	11978	XTLKER(2,C ODE):The c ode is not in the as sociated f ile.
	11979	XTLKER(3,S HORTCUT):T he shortcu t could no t be added .
	11980
	11981	SY^XTLKMGR (): Add Te rms and Sy nonyms to the Local Synonym Fi le
	11982	Reference Type:Suppo rted
	11983	Category:T oolkit—Mul ti-Term Lo ok-Up (MTL U)
	11984	ICR #:1015 3
	11985	Descriptio n:This API adds Term s and Syno nyms to th e LOCAL SY NONYM file (#8984.3) .
	11986	Format:SY^ XTLKMGR(xt lk1,xtlk2, xtlk3)
	11987	Make sure to perform the follo wing steps before ca lling this API:
	11988	NEW all no n-namespac ed variabl es.
	11989	Set all in put variab les.
	11990	Call the A PI.
	11991	Input Para meters:xtl k1:(requir ed) Associ ated file.
	11992	xtlk2:(req uired) Ter m.
	11993	xtlk3:(req uired) Syn onym (or o ptional ar ray for mu ltiple syn onyms per term).
	11994	NOTE: Use one-dimen sional arr ays wherev er support ed in ^XTL KMGR as in the follo wing examp le:
	11995	SYN(1)=<fi rst synony m>SYN(2)=< second syn onym>SYN(3 )=<third s ynonym>>D SY^ROUTINE (XTLK1,XTL K2,.SYN)
	11996	Output Var iables:XTL KER(1,FILE NAME):File not defin ed in the LOCAL LOOK UP file (# 8984.4).
	11997	XTLKER(2,T ERM):The t erm could not be add ed.
	11998	XTLKER(3,S YNONYM):Th e synonym could not be added.
	11999
	12000	Toolkit—M Unit Utili ty
	12001	Overview
	12002	M Unit is a utility (tool) tha t permits a series o f tests to be writte n to addre ss specifi c tags or entry poin ts within a project and act to verify th at the ret urn result s are as e xpected fo r that cod e. Kernel Toolkit pa tch XT7.3 81 provid es the M U nit code, but was ne ver releas ed to prod uction. It is availa ble to M d evelopers upon reque st from th e Kernel d evelopment team.
	12003	If run rou tinely any time that the proje ct is modi fied, the tests indi cate wheth er the int ended func tion has b een modifi ed inadver tently, or whether t he modific ation has had unexpe cted effec ts on othe r function ality with in the pro ject. The set of uni t tests fo r a projec t should r un rapidly (usually within a m atter of s econds) an d with min imal disru ption for developers . Another function o f unit tes ts is that they indi cate what the intend ed softwar e was writ ten to do. This can be especia lly useful when new developers start wor king with the softwa re or a pr ogrammer r eturns to a project after a pr olonged pe riod. Ensu ring that well-desig ned unit t ests are c reated for each proj ect; there fore, it d oes the fo llowing:
	12004	Assists de velopment.
	12005	Enhances m aintainabi lity.
	12006	Improves e nd-user co nfidence i n the depl oyed softw are.
	12007	NOTE: None of the Ap plication Programmin g Interfac es (APIs), extrinsic functions , or secti ons of cod e in the M Unit are callable f rom outsid e a unit t est, but a re all par t of a uni t test. M UNIT is a self-conta ined appli cation.
	12008	Introducti on to M Un it Testing
	12009	A Unit Tes t framewor k permits small test s to be wr itten to v erify that the code under exam ination is doing wha t you expe ct it to d o. General ly, the te sts are pe rformed on the small er blocks of the app lication, and do not necessari ly test al l of the f unctionali ty within the applic ation. The se tests c an be run frequently to valida te that no errors ha ve been in troduced s ubsequentl y as chang es are mad e in the c ode. The p hrase “Tes t-Driven D evelopment ” is frequ ently used to indica te the str ong use of unit test ing during developme nt; althou gh, some t hink of it as equiva lent to “T est First Developmen t”, in whi ch the tes ts for cod e are writ ten prior to writing the code. In “Test First Deve lopment”, the test s hould init ially fail (since no thing has been writt en) and th en pass af ter the co de has bee n written.
	12010	For client side lang uages, Jun it (for Ja va), DUnit (for Delp hi), NUnit and Harne ssIt (for dotNet) al l provide Unit Test frameworks . The ^XTM UNIT and ^ XTMUNIT1 r outines pr ovide the same capab ilities fo r unit tes ting M cod e. The tes ts are con sole-based (i.e., co mmand line text, not windows).
	12011	For those who have p roblems ke eping trac k of routi ne names f or unit te sting and with which applicati on they ar e associat ed, the MU NIT TEST G ROUP file (#8992.8) can be use d to maint ain groups of unit t est routin es with th e MUnit Te st Group e dit option [XTMUNIT GROUP EDIT ]. These u nit tests can be run using eit her of the following :
	12012	Menu Optio n: Run MUn it Tests f rom Test G roups opti on [XTMUNI T GROUP RU N]
	12013	Direct Mod e Utility: D RUNSET^ XTMUNIT(se tname).
	12014	While the order of p rocessing within M U nit tests can be fai rly consta nt, or at least appe ar to be s o, it is p referable to have th e unit tes ts indepen dent of th e order in which the y are run. Having de pendencies between t ests can r esult in p roblems if the order were to c hange or i f changes are made i n the test being dep ended upon .
	12015	M Unit Tes t Definiti ons
	12016	Supported References in ^XTMUN IT are:
	12017	EN
	12018	CHKTF
	12019	CHKEQ
	12020	FAIL
	12021	SUCCESS
	12022	CHKLEAKS
	12023	ISUTEST
	12024	RUNSET
	12025	Getting St arted
	12026	If you are going to modify sec tions of y our code, it is best to create a unit te st for tho se areas t hat you wa nt to work . Then, th e unit tes ts can be run as cha nges are m ade to ens ure that n othing une xpected ha s changed. For modif ications, the unit t ests are t hen writte n to refle ct the new expected behavior a nd used to ensure th at it is w hat is exp ected.
	12027	A sample u nit test c an be foun d in the ^ XTMZZUT1 r outine.
	12028	Applicatio n Programm ing Interf aces (APIs )
	12029	NOTE: None of the Ap plication Programmin g Interfac es (APIs), extrinsic functions , or secti ons of cod e in the M Unit are callable f rom outsid e a unit t est, but a re all par t of a uni t test. M UNIT is a self-conta ined appli cation.
	12030	EN^XTMUNIT (): Run Un it Tests
	12031	Reference Type:N/A; Not callab le from ou tside a un it test.
	12032	Category:T oolkit—M U nit Utilit y
	12033	ICR #:N/A
	12034	Descriptio n:This API runs unit tests. It is typica lly the fi rst comman d within a suite of unit test routines, so that th e entire s uite of te sts (multi ple routin es) can be run by ex ecuting th e first ro utine of t he suite. For exampl e, the uni t tests fo r testing M Unit can be run by :
	12035	>D ^XTMZZU T1”
	12036	The EN^XTM UNIT API s tarts the unit testi ng process .
	12037	Format:D E N^XTMUNIT( rouname,[v erbose,][b reak])
	12038	Input Para meters:rou name:(requ ired) prov ides the n ame of the routine w here the t esting sho uld be sta rted. That routine m ust have a t least on e test ent ry point ( and possib ly more) e ither spec ified as f ollows:
	12039	In the lin es immedia tely follo wing the X TENT tag a s the thir d semi-col on piece o n the line .OR
	12040	It can hav e tags wit h @TEST as the first text of t he comment for the t ag line.
	12041	verbose:(o ptional) I f it evalu ates to Tr ue (e.g., 1), it tur ns on verb ose mode, which list s each ind ividual te st being r un as well as its re sult.
	12042	break:(opt ional) If it evaluat es to True , it cause s the M Un it test pr ocess to t erminate u pon a fail ure or err or instead of contin uing until all tests have been evaluated .
	12043	Output:ret urns:Resul ts of the unit tests .
	12044
	12045	The follow ing sectio ns of code in the XT MUNIT rout ine are ad ditional t est entry points add ed by the developer; however, they are n ot callabl e by the d eveloper f rom inside or outsid e of the r outine:
	12046	STARTUP
	12047	SHUTDOWN
	12048	SETUP
	12049	TEARDOWN
	12050	XTENT: Lis t Unit Tes t Entry Po ints
	12051	XTROU: Lis t of Routi nes Contai ning Addit ional Test s
	12052	STARTUP
	12053	This secti on of code in the XT MUNIT rout ine runs b efore anyt hing else. It is use ful for se tting up a n environm ent or var iable valu es that ar e common t o all of t he tests.
	12054	SHUTDOWN
	12055	This secti on of code in the XT MUNIT rout ine runs a fter every thing else . It is us eful for s hutting do wn an envi ronment or clearing variable v alues that are commo n to all o f the test s. It can also be us ed for cle aning up g lobal or f ile entrie s that are left as a result of testing.
	12056	SETUP
	12057	This secti on of code in the XT MUNIT rout ine runs b efore ever y test. It is useful for reset ting an en vironment or variabl e values t hat are us ed by the tests.
	12058	TEARDOWN
	12059	This secti on of code in the XT MUNIT rout ine runs a fter every test. It is useful for cleani ng up an e nvironment or variab le values that are u sed by the tests.
	12060	XTENT: Lis t Unit Tes t Entry Po ints
	12061	This secti on of code in the XT MUNIT rout ine is use d to store informati on require d by the E N^XTMUNIT( ): Run Uni t Tests AP I to run a unit test . It provi des a list of unit t est entry points. Ea ch entry d escribes a group of tests.
	12062	Figure 125 : XTENT: L ist Unit T est Entry Points
	12063	;;T4;Entry point usi ng XTMENT
	12064	;;T5;Error count che ck
	12065
	12066	XTROU: Lis t of Routi nes Contai ning Addit ional Test s
	12067	This secti on of code in the XT MUNIT rout ine is use d to store informati on require d by the E N^XTMUNIT( ): Run Uni t Tests AP I to run a unit test . It provi des a list of routin es contain ing additi onal tests . It exten ds a suite of tests beyond the limits of a single routine.
	12068	Figure 126 : XTROU: L ist of Rou tines Cont aining Add itional Te sts
	12069	;;XTMZZUT2 ;
	12070	;;XTMZZUT3 ;
	12071
	12072	CHKEQ^XTMU NIT: Check Two Value s for Equi valence
	12073	Reference Type:Not c allable fr om outside a unit te st.
	12074	Category:T oolkit—M U nit Utilit y
	12075	ICR #:N/A
	12076	Descriptio n:This API runs a te st that ch ecks two v alues for equivalenc e.
	12077	Format:D C HKEQ^XTMUN IT(expect, actual,msg )
	12078	Input Para meters:exp ect:(requi red) The e xpected va lue.
	12079	actual:(re quired) Th e actual v alue.
	12080	msg:(requi red) The e rror messa ge to be g enerated i f the resu lt of the test is Fa lse (not e qual).
	12081	Output:ret urns:Retur ns:
	12082	A period o r “dot”—If the resul t of the t est is Tru e.
	12083	The <expec ted value> , the <act ual value> , and the error mess age “msg” —If the re sult of th e test is False.
	12084
	12085	CHKLEAKS^X TMUNIT(): Check for Variable L eaks
	12086	Reference Type:Not c allable fr om outside a unit te st
	12087	Category:T oolkit—M U nit Utilit y
	12088	ICR #:N/A
	12089	Descriptio n:This API runs a te st that ca n be used within uni t tests or in a stan dalone tes t for vari able leaks (those cr eated with in called code that are allowe d to leak into the c alling env ironment, unintentio nally).
	12090	Format:D C HKLEAKS^XT MUNIT(code ,testloc,. nameinpt)
	12091	Input Para meters:cod e:(require d) Contain s a comman d to be ex ecuted in the test f or leaks. For exampl e:
	12092	S X=$$NOW^ XLFDT()
	12093	testloc:(r equired) I ndicates t he locatio n under te st. For ex ample:
	12094	$$NOW^XLFD T() leak t est
	12095	Or simply:
	12096	$$NOW^XLFD T
	12097	.nameinpt: (required) This para meter is p assed by r eference, and is an array that contains a list of all variab les that t he user is passing i n and/or e xpects to be present when the code is fi nished (th e variable X would b e in the l atter cate gory, sinc e it would then be p resent). T he input i s in the f orm of an array:
	12098	NAMEINPT(“ VARNAME”)= “VARVALUE”
	12099	Where:
	12100	VARNAME—Na me of a va riable.
	12101	VARVALUE—V alue that is to be a ssigned to the varia ble before the conte nts of the code inpu t paramete r is to be executed.
	12102	Output:ret urns:Retur ns:
	12103	Inside a u nit test e nvironment —When run in a unit test envir onment, va riables th at are pre sent after the conte nts of the code inpu t paramete r is execu ted that w ere not in cluded in NAMEINPT a rray as va riables, a re listed as failure s.
	12104	Outside a unit test environmen t—When cal led outsid e of a uni t test env ironment, any leaked variables are liste d on the c urrent dev ice.
	12105
	12106	CHKTF^XTMU NIT(): Tes t Conditio nal Values
	12107	Reference Type:Not c allable fr om outside a unit te st.
	12108	Category:T oolkit—M U nit Utilit y
	12109	ICR #:N/A
	12110	Descriptio n:This API runs a te st that ch ecks condi tional val ues (True or False).
	12111	Format:D C HKTF^XTMUN IT(val,msg )
	12112	Input Para meters:val :The condi tional val ue to be t ested.
	12113	msg:The er ror messag e to be ge nerated if the resul t of the t est is Fal se.
	12114	Output:ret urns:Retur ns:
	12115	A period o r “dot”—If the resul t of the t est is Tru e.
	12116	An error m essage—If the result of the te st is Fals e.
	12117
	12118	FAIL^XTMUN IT(): Gene rate an Er ror Messag e
	12119	Reference Type:Not c allable fr om outside a unit te st
	12120	Category:T oolkit—M U nit Utilit y
	12121	ICR #:N/A
	12122	Descriptio n:This API runs a te st that si mply gener ates an er ror messag e This com mand is us eful for m ore comple x unit tes ts that ar e built wi thin the u nit test r outine its elf.
	12123	Format:D F AIL^XTMUNI T(msg)
	12124	Input Para meters:msg :(required ) The text of the er ror messag e.
	12125	Output:ret urns:Retur ns the err or message .
	12126
	12127	$$ISUTEST^ XTMUNIT: E valuate if Unit Test is Runnin g
	12128	Reference Type:Not c allable fr om outside a unit te st
	12129	Category:T oolkit—M U nit Utilit y
	12130	ICR #:N/A
	12131	Descriptio n:This ext rinsic fun ction is u sed to eva luate if a unit test is curren tly runnin g. If a te st is runn ing, it re turns a va lue of 1; otherwise, it return s a value of zero. T his can be used to s elect code to be run based on whether it is curren tly being tested (or something else that calls it is being t ested).
	12132	Format:S X =$$ISUTEST ^XTMUNIT
	12133	Input Para meters:non e.
	12134	Output:ret urns:Retur ns:
	12135	1—If a tes t is runni ng.
	12136	Zero (0)—I f a test i s not runn ing.
	12137
	12138	SUCCEED^XT MUNIT: Inc rement Tes t Counter
	12139	Reference Type:Not c allable fr om outside a unit te st
	12140	Category:T oolkit—M U nit Utilit y
	12141	ICR #:N/A
	12142	Descriptio n:This API runs a te st command that incr ements the test coun ter; write s a “dot” to the scr een for ac tivity, wh ich indica tes a succ essful tes t. This co mmand is u seful for indicating a success ful test w ithin a mo re complex unit test built wit hin the un it test ro utine itse lf, and is the count erpart to the FAIL^X TMUNIT(): Generate a n Error Me ssage API.
	12143	Format:D S UCCEED^XTM UNIT
	12144	Input Para meters:non e.
	12145	Output:ret urns:Incre ments test counter; writes a p eriod or “ dot” to th e screen f or activit y, which i ndicates a successfu l test.
	12146
	12147	Sample M U nit Utilit y Output
	12148	Figure 127 is an exa mple of th e output f rom runnin g a suite of unit te sts to tes t M Unit:
	12149	Figure 127 : Sample o utput from the M Uni t test too l—Verbose
	12150	VISTA>D ^X TMZZUT1
	12151
	12152	T1 - - Mak e sure Sta rt-up Ran. ---------- ---------- ---------- ---------- - [OK]
	12153	T2 - - Mak e sure Set -up runs.- ---------- ---------- ---------- ---------- - [OK]
	12154	T3 - - Mak e sure Tea rdown runs .--------- ---------- ---------- ---------- - [OK]
	12155	T4 - Entry point usi ng XTMENT- ---------- ---------- ---------- ---------- - [OK]
	12156	T5 - Error count che ck
	12157	T5^XTMZZUT 1 - Error count chec k - This i s an inten tional fai lure.
	12158	.
	12159	T5^XTMZZUT 1 - Error count chec k - Intent ionally th rowing a f ailure
	12160	.--------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12161	T6 - Succe ed Entry P oint...--- ---------- ---------- ---------- ---------- - [OK]
	12162	T7 - Make sure we wr ite to pri ncipal eve n though w e are on a nother dev ice[OK]
	12163	T8 - If IO starts wi th another device, w rite to th at device as if it’s the princ i
	12164	pal device ---------- ---------- ---------- ---------- ---------- ---------- - [OK]
	12165	T11 - An @ TEST Entry point in Another Ro utine invo ked throug h XTROU of fsets.[OK]
	12166	T12 - An X TENT offse t entry po int in Ano ther Routi ne invoked through X TROU offse
	12167	ts.------- ---------- ---------- ---------- ---------- ---------- ---------- - [OK]
	12168	MAIN - - T est covera ge calcula tions----- ---------- ---------- ---------- - [OK]
	12169	NEWSTYLE - identify new style test indic ator funct ionality.- ---------- - [OK]
	12170	OLDSTYLE - identify old style test indi cator func tionality. .--------- - [OK]
	12171	OLDSTYL1 - identify old style test indi cator 2.-- ---------- ---------- - [OK]
	12172	BADCHKEQ - CHKEQ sh ould fail on unequal value
	12173	BADCHKEQ^X TMZZUT5 - CHKEQ sho uld fail o n unequal value - <4 > vs <3> - SET UNEQU
	12174	AL ON PURP OSE - SHOU LD FAIL
	12175	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12176	BADCHKTF - CHKTF sh ould fail on false v alue
	12177	BADCHKTF^X TMZZUT5 - CHKTF sho uld fail o n false va lue - SET FALSE (0) ON PURPOSE
	12178	- SHOULD FAIL
	12179	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12180	BADERROR - throws a n error on purpose
	12181	BADERROR^X TMZZUT5 - throws an error on purpose - Error: <UN DEFINED>BA DERROR+6^X
	12182	TMZZUT5 *Q
	12183	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12184	CALLFAIL - called F AIL to tes t it
	12185	CALLFAIL^X TMZZUT5 - called FA IL to test it - Call ed FAIL to test it
	12186	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12187	LEAKSOK - check leak s should b e ok------ ---------- ---------- ---------- - [OK]
	12188	LEAKSBAD - check lea ks with le ak
	12189	LEAKSBAD^X TMZZUT5 - check leak s with lea k - LEAKSB AD TEST - X NOT SPEC IFIED VARI
	12190	ABLE LEAK: X
	12191	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12192	NVLDARG1 - check inv alid arg i n CHKEQ
	12193	NVLDARG1^X TMZZUT5 - check inva lid arg in CHKEQ - N O VALUES I NPUT TO CH KEQ^XTU -
	12194	no evaluat ion possib le
	12195	---------- ---------- ---------- ---------- ---------- ---------- ---------- - [FAIL]
	12196	ISUTEST - check ISUT EST inside unit test .--------- ---------- ---------- - [OK]
	12197	CHKCMDLN - check com mand line processing of XTMZZU T5-------- ---------- - [OK]
	12198	CHKGUI - c heck GUI p rocessing of XTMZZUT 5--------- ---------- ---------- - [OK]
	12199	CKGUISET - check lis t of tests returned by GUISET- ---------- ---------- - [OK]
	12200	NEWSTYLE - test retu rn of vali d new styl e or @TEST indicator s...------ - [OK]
	12201
	12202	Ran 5 Rout ines, 26 E ntry Tags
	12203	Checked 25 tests, wi th 7 failu res and en countered 1 error.
	12204
	12205	Toolkit—Pa rameter To ols
	12206	Overview
	12207	Parameter Tools is a generic m ethod of h andling pa rameter de finitions, assignmen ts, and re trieval. A parameter may be de fined for various en tities whe re an enti ty is the level at w hich you w ant to all ow the par ameter def ined (e.g. , package level, sys tem level, division level, loc ation leve l, user le vel, etc.) . A develo per can th en determi ne in whic h order th e values a ssigned to given ent ities are interprete d.
	12208	REF: Integ ration Con trol Regis tration (I CR) #2263 defines th e various callable e ntry point s in the X PAR routin e.ICR #233 6 defines the variou s callable entry poi nts in the XPAREDIT routine.
	12209	Definition s
	12210	The follow ing are so me basic d efinitions used by P arameter T ools:
	12211	Entity
	12212	An entity is a level at which you can de fine a par ameter. Th e entities allowed a re stored in the PAR AMETER ENT ITY file ( #8989.518) . The list of allowa ble entiti es at the time this utility wa s released was as fo llows:
	12213	Table 33: Parameter Tool—Param eter entit y levels
	12214	Entity Pre fix
	12215	Message
	12216	Points to File
	12217	PKG
	12218	Package
	12219	PACKAGE (# 9.4)
	12220	SYS
	12221	System
	12222	DOMAIN (#4 .2)
	12223	DIV
	12224	Division
	12225	INSTITUTIO N (#4)
	12226	SRV
	12227	Service
	12228	SERVICE/SE CTION (#49 )
	12229	LOC
	12230	Location
	12231	HOSPITAL L OCATION (# 44)
	12232	TEA
	12233	Team
	12234	TEAM (#404 .51)
	12235	CLS
	12236	Class
	12237	USR CLASS (#8930)
	12238	USR
	12239	User
	12240	NEW PERSON (#200)
	12241	BED
	12242	Room-Bed
	12243	ROOM-BED ( #405.4)
	12244	OTL
	12245	Team (OE/R R)
	12246	OE/RR LIST (#100.21)
	12247	DEV
	12248	Device
	12249	DEVICE (#3 .5)
	12250
	12251	NOTE: Entr ies are ma intained v ia Kernel Toolkit pa tches. Ent ries exist ing in the file at t he time it is refere nced are c onsidered supported.
	12252	Parameter
	12253	A paramete r is the a ctual name under whi ch values are stored . The name of the pa rameter mu st be name spaced and it must b e unique. Parameters can be de fined to s tore the t ypical pac kage param eter data (e.g., the default a dd order s creen in O E/RR), but they can also be us ed to stor e GUI appl ication sc reen setti ngs a user has selec ted (e.g., font or w indow widt h). When a parameter is define d, the ent ities that can set t hat parame ter are al so defined . The defi nition of parameters is stored in the PA RAMETER DE FINITION f ile (#8989 .51).
	12254	Value
	12255	A value ma y be assig ned to eve ry paramet er for the entities allowed in the param eter defin ition. Val ues are st ored in th e PARAMETE RS file (# 8989.5).
	12256	Instance
	12257	Most param eters set instance t o 1. Insta nces are u sed when m ore than o ne value m ay be assi gned to a given enti ty/paramet er combina tion. An e xample of this would be lab co llection t imes at a division. A single d ivision ma y have mul tiple coll ection tim es. Each c ollection time would be assign ed a uniqu e instance .
	12258	Parameter Template
	12259	A paramete r template is simila r to an in put templa te. It con tains a li st of para meters tha t can be e ntered thr ough an in put sessio n (e.g., o ption). Te mplates ar e stored i n the PARA METER TEMP LATE File (#8989.52) . Entries in this fi le must al so be name spaced.
	12260	Applicatio n Programm ing Interf aces (APIs )
	12261	ADD^XPAR() : Add Para meter Valu e
	12262	Reference Type:Suppo rted
	12263	Category:T oolkit—Par ameter Too ls
	12264	ICR #:2263
	12265	Descriptio n:This API adds a ne w paramete r value as an entry to the PAR AMETERS fi le (#8989. 5) if the Entity/Par ameter/Ins tance comb ination do es not alr eady exist .
	12266	REF: For descriptiv e informat ion about the elemen ts and how they are used in th e callable entry poi nts into X PAR, see t he “Defini tions” sec tion.
	12267	Format:ADD ^XPAR(enti ty,paramet er[,instan ce],value[ ,.error])
	12268	Input / Ou tput
	12269	Parameters See EN^XPA RFor the d efinition of the inp ut and out put parame ters used in this AP I, see the EN^XPAR() : Add, Cha nge, Delet e Paramete rs API.
	12270
	12271	Example:
	12272	>D ADD^XPA R(“PKG.KER NEL”,“XPAR TEST FREE TEXT”,,“T oday Good” ,.ERROR)
	12273
	12274	CHG^XPAR() : Change P arameter V alue
	12275	Reference Type:Suppo rted
	12276	Category:T oolkit—Par ameter Too ls
	12277	ICR #:2263
	12278	Descriptio n:This API changes t he value a ssigned to an existi ng paramet er if the Entity/Par ameter/Ins tance comb ination al ready exis ts.
	12279	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12280	Format:CHG ^XPAR(enti ty,paramet er[,instan ce],value[ ,.error])
	12281	Input / Ou tput
	12282	Parameters :See EN^XP ARFor the definition of the in put and ou tput param eters used in this A PI, see th e EN^XPAR( ): Add, Ch ange, Dele te Paramet ers API.
	12283
	12284	Example
	12285	>D CHG^XPA R(“PKG.KER NEL”,“XPAR TEST FREE TEXT”,,“T omorrow Ho t”,.ERROR)
	12286
	12287	DEL^XPAR() : Delete P arameter V alue
	12288	Reference Type:Suppo rted
	12289	Category:T oolkit—Par ameter Too ls
	12290	ICR #:2263
	12291	Descriptio n:This API deletes a n existing parameter instance if the val ue assigne d is “@”.
	12292	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12293	Format:DEL ^XPAR(enti ty,paramet er[,instan ce][,.erro r])
	12294	Input / Ou tput
	12295	Parameters :See EN^XP ARFor the definition of the in put and ou tput param eters used in this A PI, see th e EN^XPAR( ): Add, Ch ange, Dele te Paramet ers API.
	12296
	12297	Example
	12298	>D DEL^XPA R(“PKG.KER NEL”,“XPAR TEST FREE TEXT”,),. ERROR) I E RROR>0 W ! .ERROR
	12299
	12300	EN^XPAR(): Add, Chan ge, Delete Parameter s
	12301	Reference Type:Suppo rted
	12302	Category:T oolkit—Par ameter Too ls
	12303	ICR #:2263
	12304	Descriptio n:This API performs any one of the follo wing funct ions:
	12305	Adds the v alue as a new entry to the PAR AMETERS fi le (#8989. 5) if the Entity\|Par ameter\|Ins tance comb ination do es not alr eady exist .
	12306	Changes th e value as signed to the parame ter in the PARAMETER S file (#8 989.5) if the Entity \|Parameter \|Instance combinatio n already exists.
	12307	Deletes th e paramete r instance in the PA RAMETERS f ile (#8989 .5) if the value ass igned is “ @”.
	12308	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12309	Format:EN^ XPAR(entit y,paramete r[,instanc e],value[, .error])
	12310	Input Para meters:ent ity:(requi red) Entit y can be s et to the following:
	12311	Internal v ariable po inter (nnn ;GLO(123,)
	12312	External f ormat of t he variabl e pointer using the three-char acter pref ix (prefix .entryname )
	12313	Prefix alo ne to set the parame ter based on the cur rent entit y selected . This wor ks for the following entities:
	12314	“USR”—Uses current v alue of DU Z.
	12315	“DIV”—Uses current v alue of DU Z(2).
	12316	“SYS”—Uses system (d omain).
	12317	“PKG”—Uses the packa ge to whic h the para meter belo ngs.
	12318	parameter: (required) Can be pa ssed in ex ternal or internal f ormat. Ide ntifies th e name or internal e ntry numbe r (IEN) of the param eter as de fined in t he PARAMET ER DEFINIT ION file ( #8989.51).
	12319	instance:( optional) Defaults t o 1 if not passed. C an be pass ed in exte rnal or in ternal for mat. Inter nal format requires that the v alue be pr eceded by the grave accent (`) character .
	12320	value:(req uired) Can be passed in extern al or inte rnal forma t. If usin g internal format fo r a pointe r type par ameter, th e value mu st be prec eded by th e accent g rave (`) c haracter.
	12321	If the val ue is bein g assigned to a word -processin g paramete r, the tex t can be p assed in t he subordi nate nodes of Value (e.g., Val ue(1,0)=Te xt) and th e variable “Value” i tself can be defined as a titl e or descr iption of the text.
	12322	Output Par ameter:.er ror:(optio nal) If us ed, must b e passed i n by refer ence. It r eturns any error con dition tha t may occu r:
	12323	0 (Zero)—I f no error occurs.
	12324	#^errortex t—If an er ror does o ccur. The “#” is the number in the VA Fi leMan DIAL OG file (# .84) and t he “errort ext” descr ibes the e rror.
	12325
	12326	Example
	12327	>D EN^XPAR (“SYS”,“XP AR TEST FR EE TEXT”,0 ,“Good tim es”,.ERROR )
	12328	>D EN^XPAR (“SYS”,“XP AR TEST FR EE TEXT”,1 ,“to night ”,.ERROR)
	12329
	12330	ENVAL^XPAR (): Return All Param eter Insta nces
	12331	Reference Type:Suppo rted
	12332	Category:T oolkit—Par ameter Too ls
	12333	ICR #:2263
	12334	Descriptio n:This API returns a ll paramet er instanc es.
	12335	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12336	Format:ENV AL^XPAR(.l ist,parame ter,instan ce[,.error ][,gbl])
	12337	Input / Ou tput
	12338	Parameters :.list:(re quired) If the gbl p arameter i s set to 1 , then the .list par ameter bec omes an in put and ho lds the cl osed root of a globa l where th e GETLST^X PAR(): Ret urn All In stances of a Paramet er API sho uld put th e output. For exampl e:
	12339	$NA(^TMP($ J,“XPAR”))
	12340	Input Para meters:par ameter:(re quired) Fo r a descri ption of t his parame ter, see t he EN^XPAR (): Add, C hange, Del ete Parame ters API.
	12341	instance:( required) For a desc ription of this para meter, see the EN^XP AR(): Add, Change, D elete Para meters API .
	12342	gbl:(optio nal) If th is optiona l paramete r is set t o 1, then the parame ter “.list ” must be set before the call to the clo sed global root wher e the retu rn data sh ould be pu t. For exa mple:
	12343	S LIST=$NA (^TMP($J)) ENVAL^XPA R(LIST,par ,inst,.err or,1
	12344	If this op tional var iable is s et to 1. T hen the pa rameter Li st must be set befor e the call to the cl osed globa l root whe re the ret urn data s hould be p ut. For ex ample:
	12345	GETLST^XPA R($NA(^TMP ($J)),ent, par,fmt,.e rror,1)
	12346	Output Par ameters:.e rror:(opti onal) For a descript ion of thi s paramete r, see the EN^XPAR() : Add, Cha nge, Delet e Paramete rs API.
	12347
	12348	$$GET^XPAR (): Return an Instan ce of a Pa rameter
	12349	Reference Type:Suppo rted
	12350	Category:T oolkit—Par ameter Too ls
	12351	ICR #:2263
	12352	Descriptio n:This ext rinsic fun ction retr ieves the value of a parameter . The valu e is retur ned from t his call i n the form at defined by the in put parame ter named “format.”
	12353	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12354	Format:$$G ET^XPAR(en tity,param eter,insta nce[,forma t])
	12355	Input Para meters:ent ity:(requi red) Entit y is defin ed as the single ent ity or gro up of enti ties you w ant to loo k at in or der to ret rieve the value. Ent ities may be passed in interna l or exter nal format (e.g., LO C.PULMONAR Y or LOC.’ 57 or 57;S C(). The l ist of ent ities in t his variab le may be defined as follows:
	12356	A single e ntity to l ook at (e. g., LOC.PU LMONARY).
	12357	The word “ ALL” that tells the utility to look for values ass igned to t he paramet er using t he entity precedence defined i n the PARA METER DEFI NITION fil e (#8989.5 1).
	12358	A list of entities y ou want to search (e .g., ”USR^ LOC^SYS^PK G”). The l ist is sea rched from left to r ight with the first value foun d returned .
	12359	Items 2 or 3 with sp ecific ent ity values reference d such as:
	12360	ALL^LOC.PU LMONARY—To look at t he defined entity pr ecedence, but when l ooking at location, only look at the PUL MONARY loc ation.
	12361	USR^LOC.PU LMONARY^SY S^PKG—To l ook for va lues for a ll current user, PUL MONARY loc ation, sys tem, or pa ckage).
	12362	parameter: (required) For a des cription o f this par ameter, se e the EN^X PAR(): Add , Change, Delete Par ameters AP I.
	12363	instance:( required) For a desc ription of this para meter, see the EN^XP AR(): Add, Change, D elete Para meters API .
	12364	format:(op tional) Th e format i nput param eter deter mines how the value is returne d. It can be set to the follow ing:
	12365	“I”—Intern al; return s list(#) = “interna l value”.
	12366	“Q”—Quick; returns l ist(#) = “ internal i nstance^in ternal val ue”. Retur ns the val ue in the quickest m anner (def ault if no t specifie d).
	12367	“E”—Extern al; return s list(#) = “externa l instance ^external value”.
	12368	“B”—Both; returns bo th list(#, “N”) = “in ternal ins tance^exte rnal insta nce” and l ist(#,“V”) = “intern al value^e xternal va lue”.
	12369	“N”—Return s list(#) = “interna l value^ex ternal val ue”.
	12370	Output:ret urns:Retur ns the par ameter val ue in the format def ined by th e format i nput param eter.
	12371
	12372	GETLST^XPA R(): Retur n All Inst ances of a Parameter
	12373	Reference Type:Suppo rted
	12374	Category:T oolkit—Par ameter Too ls
	12375	ICR #:2263
	12376	Descriptio n:This API is simila r to the E NVAL^XPAR( ): Return All Parame ter Instan ces API; h owever, it returns a ll instanc es of a pa rameter.
	12377	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12378	Format:GET LST^XPAR(. list,entit y,paramete r[,format] [,.error][ ,gbl])
	12379	Input/ Out put
	12380	Parameters :.list:(re quired) Th e array pa ssed as Li st is retu rned with all of the possible values ass igned to t he paramet er.
	12381	REF: To se e how this data can be returne d, see the “format” parameter descriptio n.
	12382	If the gbl parameter is set to 1, then t he .list p arameter b ecomes an input and holds the closed roo t of a glo bal where the GETLST ^XPAR API should put the outpu t [i.e., $ NA(^TMP($J ,“XPAR”))] .
	12383	Input Para meters:
	12384	entity:(re quired) Fo r a descri ption of t his parame ter, see t he EN^XPAR (): Add, C hange, Del ete Parame ters API.
	12385	parameter: (required) For a des cription o f this par ameter, se e the EN^X PAR(): Add , Change, Delete Par ameters AP I.
	12386	format:(op tional) Fo r a descri ption of t his parame ter, see t he $$GET^X PAR(): Ret urn an Ins tance of a Parameter API.
	12387	gbl:(optio nal) If th is optiona l variable is set to 1. Then t he paramet er “.list” must be s et before the call t o the clos ed global root where the retur n data sho uld be put . For exam ple:
	12388	GETLST^XPA R($NA(^TMP ($J)),ent, par,fmt,.e rror,1)
	12389	Output Par ameters:.e rror:(opti onal) For a descript ion of thi s paramete r, see the EN^XPAR() : Add, Cha nge, Delet e Paramete rs API.
	12390
	12391	Example:
	12392	>D GETLST^ XPAR(.LIST ,“SYS”,“XP AR TEST MU LTI FREE T EXT”,,.ERR OR)
	12393
	12394	GETWP^XPAR (): Return Word-proc essing Tex t
	12395	Reference Type:Suppo rted
	12396	Category:T oolkit—Par ameter Too ls
	12397	ICR #:2263
	12398	Descriptio n:This API returns w ord-proces sing text in the ret urnedtext parameter. The retur nedtext pa rameter it self conta ins the va lue field, which is free text that may c ontain a t itle, desc ription, e tc. The wo rd-process ing text i s returned in return edtext(#,0 ).
	12399	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12400	Format:GET WP^XPAR(re turnedtext ,entity,pa rameter[,i nstance][, .error])
	12401	Input / Ou tput
	12402	Parameters :.returned text:(requ ired) This parameter is define d as the n ame of an array in w hich you w ant the te xt returne d. The .re turnedtext parameter is set to the title , descript ion, etc. The actual word-proc essing tex t is retur ned in ret urnedtext( #,0). For example:
	12403	>returnedt ext=“Selec t Notes He lp”>return edtext(1,0 )=“To sele ct a progr ess note f rom the li st, “>retu rnedtext(2 ,0)=“click on the da te/title o f the note .”
	12404	Input Para meters:ent ity:(requi red) For a descripti on of this parameter , see the EN^XPAR(): Add, Chan ge, Delete Parameter s API.
	12405	parameter: (required) For a des cription o f this par ameter, se e the EN^X PAR(): Add , Change, Delete Par ameters AP I.
	12406	instance:( optional) For a desc ription of this para meter, see the EN^XP AR(): Add, Change, D elete Para meters API .
	12407	Output Par ameters:.e rror(optio nal) For a descripti on of this parameter , see the EN^XPAR(): Add, Chan ge, Delete Parameter s API.
	12408
	12409	Example:
	12410	>D GETWP^X PAR(.X,“PK G”,“ORW HE LP”,“lstNo tes”,.ERRO R)
	12411
	12412	NDEL^XPAR( ): Delete All Instan ces of a P arameter
	12413	Reference Type:Suppo rted
	12414	Category:T oolkit—Par ameter Too ls
	12415	ICR #:2263
	12416	Descriptio n:This API deletes t he value f or all ins tances of a paramete r for a gi ven entity .
	12417	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12418	Forma t:ND EL^XPAR(en tity,param eter[,.err or])
	12419	Input / Ou tput
	12420	Parameters :See EN^XP ARFor the definition of the in put and ou tput param eters used in this A PI, see th e EN^XPAR( ): Add, Ch ange, Dele te Paramet ers API.
	12421
	12422	Example
	12423	>D NDEL^XP AR(“SYS”,“ XPAR TEST MULTI FREE TEXT”,.ER ROR)
	12424
	12425	PUT^XPAR() : Add/Upda te Paramet er Instanc e
	12426	Reference Type:Suppo rted
	12427	Category:T oolkit—Par ameter Too ls
	12428	ICR #:2263
	12429	Descriptio n:This API adds or u pdates a p arameter i nstance an d bypass t he input t ransforms.
	12430	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12431	Format:PUT ^XPAR(enti ty,paramet er[,instan ce],value[ ,.error])
	12432	Input / Ou tput
	12433	Parameters :See EN^XP ARFor the definition of the in put and ou tput param eters used in this A PI, see th e EN^XPAR( ): Add, Ch ange, Dele te Paramet ers API.
	12434
	12435	Example:
	12436	>D PUT^XPA R(“SYS”,“X PAR TEST M ULTI FREE TEXT”,0,“G ood times” ,.ERROR)
	12437
	12438	REP^XPAR() : Replace Instance V alue
	12439	Reference Type:Suppo rted
	12440	Category:T oolkit—Par ameter Too ls
	12441	ICR #:2263
	12442	Descriptio n:This API replaces the value of an inst ance with another va lue.
	12443	REF: For d escriptive informati on about t he element s and how they are u sed in the callable entry poin ts into XP AR, see th e “Definit ions” sect ion.
	12444	Format:REP ^XPAR(enti ty,paramet er,current instance,n ewinstance [,.error])
	12445	Input Para meters:ent ity:(requi red) For a descripti on of this parameter , see the EN^XPAR(): Add, Chan ge, Delete Parameter s API.
	12446	parameter: (required) For a des cription o f this par ameter, se e the EN^X PAR(): Add , Change, Delete Par ameters AP I.
	12447	currentins tance:(req uired) The instance for which the value is current ly defined .
	12448	newinstanc e:(require d) The ins tance to w hich you w ant to ass ign the va lue that i s currentl y assigned to curren tinstance.
	12449	Output Par ameters:.e rror:(opti onal) For a descript ion of thi s paramete r, see the EN^XPAR() : Add, Cha nge, Delet e Paramete rs API.
	12450
	12451	BLDLST^XPA REDIT(): R eturn All Entities o f a Parame ter
	12452	Reference Type:Suppo rted
	12453	Category:T oolkit—Par ameter Too ls
	12454	ICR #:2336
	12455	Descriptio n:This API returns i n the arra y “list” a ll entitie s allowed for the in put parame ter named “parameter .”
	12456	Format:BLD LST^XPARED IT(.list,p arameter)
	12457	Input Para meters:.li st:(requir ed) Name o f array to receive o utput.
	12458	parameter: (required) Internal Entry Numb er (IEN) o f entry in the PARAM ETER DEFIN ITION file (#8989.51 ).
	12459	Output Par ameters:.l ist:The ar ray passed as “list” is return ed with al l of the p ossible va lues assig ned to the parameter .
	12460	Data is re turned in the follow ing format :
	12461	list(ent,i nst)=val
	12462
	12463	EDIT^XPARE DIT(): Edi t Instance and Value of a Para meter
	12464	Reference Type:Suppo rted
	12465	Category:T oolkit—Par ameter Too ls
	12466	ICR #:2336
	12467	Descriptio n:This API interacti vely edits the insta nce (if mu ltiple ins tances are allowed) and the va lue for a parameter associated with a gi ven entity .
	12468	Format:EDI T^XPAREDIT (entity,pa rameter)
	12469	Input Para meters:ent ity:(requi red) Ident ifies the specific e ntity for which a pa rameter ca n be edite d. The ent ity must b e in varia ble pointe r format.
	12470	parameter: (required) Identifie s the para meter that should be edited. P arameter s hould cont ain two pi eces:
	12471	IEN^Displa yNameOfPar ameter
	12472	Output:res ults:Retur ns paramet er for Int eractive e dits.
	12473
	12474	EDITPAR^XP AREDIT(): Edit Singl e Paramete r
	12475	Reference Type:Suppo rted
	12476	Category:T oolkit—Par ameter Too ls
	12477	ICR #:2336
	12478	Descriptio n:This API edits a s ingle para meter.
	12479	Format:EDI TPAR^XPARE DIT(parame ter)
	12480	Input Para meters:par ameter:(re quired) Fo r a descri ption of t his parame ter, see t he EN^XPAR (): Add, C hange, Del ete Parame ters API.
	12481	Output:ret urns:Retur ns request ed paramet er.
	12482
	12483	EN^XPAREDI T: Paramet er Edit Pr ompt
	12484	Reference Type:Suppo rted
	12485	Category:T oolkit—Par ameter Too ls
	12486	ICR #:2336
	12487	Descriptio n:This API prompts t he user fo r a parame ter to edi t. This is provided as a tool for develo pers and i s not inte nded for e xported ca lls as it allows edi ting of an y paramete r.
	12488	Format:EN^ XPAREDIT
	12489	Input Para meters:non e.
	12490	Output:non e.
	12491
	12492	GETENT^XPA REDIT(): P rompt for Entity Bas ed on Para meter
	12493	Reference Type:Suppo rted
	12494	Category:T oolkit—Par ameter Too ls
	12495	ICR #:2336
	12496	Descriptio n:This API interacti vely promp ts for an entity, ba sed on the definitio n of a par ameter.
	12497	Format:GET ENT^XPARED IT(.entity ,parameter [,.onlyone ?])
	12498	Input Para meters:.en tity:(requ ired) Retu rns the se lected ent ity in var iable poin ter format .
	12499	parameter: (required) Identifie s the para meter that should be edited. P arameter s hould cont ain two pi eces:
	12500	IEN^Displa yNameOfPar ameter
	12501	Output:.on lyone?:(op tional) Re turns “1” if there i s only one possible entity for the value . For exam ple:
	12502	1—If the p arameter c an only be set for t he system, onlyone?
	12503	0—If the p arameter c ould be se t for any location, onlyone?
	12504
	12505	GETPAR^XPA REDIT(): S elect Para meter Defi nition Fil e
	12506	Reference Type:Suppo rted
	12507	Category:T oolkit—Par ameter Too ls
	12508	ICR #:2336
	12509	Descriptio n:This API allows th e user to select the PARAMETER DEFINITIO N file (#8 989.51) en try.
	12510	Format:GET PAR^XPARED IT(.variab le)
	12511	Make sure to perform the follo wing steps before ca lling this API:
	12512	NEW all no n-namespac ed variabl es.
	12513	Set all in put variab les.
	12514	Call the A PI.
	12515	Input Para meters:.va riable:(re quired) Th e name of the variab le where d ata is ret urned.
	12516	Output Var iables:.OU TPUTVALU:R eturns the value Y i n standard DIC looku p format.
	12517
	12518	TED^XPARED IT(): Edit Template Parameters (No Dash Dividers)
	12519	Reference Type:Suppo rted
	12520	Category:T oolkit—Par ameter Too ls
	12521	ICR #:2336
	12522	Descriptio n:This API allows ed iting of p arameters defined in a templat e. The par ameters in the templ ate are pr ompted in VA FileMan style—pro mpt by pro mpt. No da shed line dividers a re display ed between each para meter.
	12523	Since the dashed lin e headers are suppre ssed, it i s importan t to defin e the VALU E TERM for each para meter in t he templat e, as this is what p rompts for the value .
	12524	Format:TED ^XPAREDIT( template[, reviewflag s][,allent ities])
	12525	Input Para meters:tem plate:(req uired) The Internal Entry Numb er (IEN) o r NAME of an entry i n the PARA METER TEMP LATE file (#8989.52) .
	12526	reviewflag s:(optiona l) There a re two fla gs (A and B) that ca n be used individual ly, togeth er, or not at all:
	12527	A—Indicate s that the new value s for the parameters in the te mplate are displayed after the prompting is done.
	12528	B—Indicate s that the current v alues of t he paramet ers are di splayed be fore editi ng.
	12529	allentitie s:(optiona l) This is a variabl e pointer that shoul d be used as the ent ity for al l paramete rs in the template. If left bl ank, promp ting for t he entity is done as defined i n the PARA METER TEMP LATE file (#8989.52) .
	12530	Output:non e.
	12531
	12532	TEDH^XPARE DIT(): Edi t Template Parameter s (with Da sh Divider s)
	12533	Reference Type:Suppo rted
	12534	Category:T oolkit—Par ameter Too ls
	12535	ICR #:2336
	12536	Descriptio n:This API is simila r to the T ED^XPAREDI T(): Edit Template P arameters (No Dash D ividers) A PI except that the d ashed line headers a re shown b etween eac h paramete r.
	12537	It allows editing of parameter s defined in a templ ate. The p arameters in the tem plate are prompted i n VA FileM an style—p rompt by p rompt.
	12538	Format:TED H^XPAREDIT (template[ ,reviewfla gs][,allen tities])
	12539	Input Para meters:tem plate:(req uired) For a descrip tion of th is paramet er, see th e TED^XPAR EDIT(): Ed it Templat e Paramete rs (No Das h Dividers ) API.
	12540	reviewflag s:(optiona l) For a d escription of this p arameter, see the TE D^XPAREDIT (): Edit T emplate Pa rameters ( No Dash Di viders) AP I.
	12541	allentitie s:(optiona l) For a d escription of this p arameter, see the TE D^XPAREDIT (): Edit T emplate Pa rameters ( No Dash Di viders) AP I.
	12542	Output:non e.
	12543
	12544	Toolkit—VH A Unique I D (VUID) A PIs
	12545	GETIREF^XT ID(): Get IREF (Term /Concept)
	12546	Reference Type:Suppo rted
	12547	Category:T oolkit—VHA Unique ID (VUID)
	12548	ICR #:4631
	12549	Descriptio n:This API searches and return s a list o f terms/co ncepts for a given V HA Unique ID (VUID; i.e., “vui d” input p arameter). Filtering of the li st is appl ied when t he followi ng optiona l input pa rameters a re defined :
	12550	file
	12551	field
	12552	master
	12553	Format:GET IREF^XTID( [file][,fi eld],vuid, array[,mas ter])
	12554	Input Para meters:fil e:(optiona l) VistA f ile/subfil e number w here term/ concept is defined.
	12555	Defined—If defined, the search is limite d to those term/conc epts that exist in t hat file a nd have th e VUID ass igned to t he “vuid” input para meter.
	12556	Not Define d—If not d efined, th e search i ncludes te rm/concept s that hav e the VUID assigned to “vuid” input para meter and can exist in both fi le terms a nd in SET OF CODES t erms.
	12557	field:(opt ional) Fie ld number, in the “f ile” input parameter , where te rm/concept is define d.
	12558	Defined—Th e search f inds those terms/con cepts that have the VUID assig ned to the “vuid” in put parame ter and is limited t o those te rms/concep ts that ex ist in the given fil e/field co mbination.
	12559	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12560	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12561	Not Define d—The sear ch finds t hose terms /concepts that have the VUID a ssigned to the “vuid ” input pa rameter an d is limit ed to thos e terms/co ncepts fou nd in the file defin ed in the “file” inp ut paramet er.
	12562	vuid:(requ ired) The VHA Unique ID (VUID) value, wh ich is spe cified to limit the search.
	12563	array:(req uired) The name of t he array ( local or g lobal) whe re results of the se arch is st ored.
	12564	master:(op tional) Fl ag to limi t the sear ch of term s based on the value of the MA STER ENTRY FOR VUID field.
	12565	Returns:
	12566	0—Include all terms.
	12567	1—Include only those terms des ignated as MASTER EN TRY FOR VU ID.
	12568	Output:arr ay:Returns the given array pop ulated as follows:
	12569	@TARRAY = <list coun t> @TARRAY @(<file#>, <field#>,< internalre ference>) = <status info>
	12570	Where the <status in fo> is def ined as “< internal v alue>^<VA FileMan ef fective da te/time>^< external v alue>^<mas ter entry? > ”
	12571	Empty Arra y—Unpopula ted array when no en tries are found.
	12572	Error Arra y—When an error occu rs, the ar ray is pop ulated as follows:
	12573	@TARRAY(“E RROR”)=“<e rror messa ge>”
	12574
	12575	Examples
	12576	Example 1
	12577	Figure 128 : GETIREF^ XTID API—E xample 1
	12578	>N array S array=“MY ARRAY”
	12579	>S file=16 000009,fie ld=.01,vui d=12343,ma ster=0
	12580	>D GETIREF ^XTID(file ,field,vui d,array,ma ster)
	12581	>ZW MYARRA Y
	12582
	12583	MYARRAY=2
	12584	MYARRAY(16 000009,.01 ,“1,”)=1^3 050202.153 242^ACTIVE ^0
	12585	MYARRAY(16 000009,.01 ,“3,”)=0^3 050215.075 84^INACTIV E^1
	12586
	12587	Example 2
	12588	When no en tries are found, the named arr ay is popu lated as f ollows.
	12589	>ZW MYARRA Y
	12590
	12591	MYARRAY=0
	12592
	12593	Example 3
	12594	When an er ror occurs , the name d array is populated as follow s:
	12595	>ZW MYARRA Y
	12596	MYARRAY(“E RROR”)=<er ror messag e>
	12597
	12598	$$GETMASTR ^XTID(): G et Master VUID Flag (Term/Conc ept)
	12599	Reference Type:Suppo rted
	12600	Category:T oolkit—VHA Unique ID (VUID)
	12601	ICR #:4631
	12602	Descriptio n:This ext rinsic fun ction retr ieves the value of t he flag MA STER ENTRY FOR VUID for a give n term/con cept refer ence.
	12603	Format:$$G ETMASTR^XT ID(file[,f ield],iref )
	12604	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12605	field:(opt ional) Fie ld number in the “fi le” input parameter where term /concept i s defined.
	12606	iref:(requ ired) Inte rnal refer ence for t erm/concep t:
	12607	File Entri es—This is an IENS. For exampl e:iref=“5, ”
	12608	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:iref = 3 oriref = “f” ori ref = “M”
	12609	Output:ret urns:Retur ns results of operat ion as fol lows:
	12610	Successful —Internal value of t he MASTER ENTRY FOR VUID field as follow s:
	12611	0—NO.
	12612	1—YES.
	12613	Unsuccessf ul—^<error message>
	12614
	12615	Examples
	12616	Example 1
	12617	For terms defined in fields th at are SET OF CODES:
	12618	>S file=2, field=.02, iref=“M”
	12619	>W $$GETMA STR^XTID(f ile,field, iref)
	12620	1
	12621
	12622	Example 2
	12623	For terms defined in a single file:
	12624	>S file=16 000009,fie ld=.01,ire f=“3,”
	12625	>W $$GETMA STR^XTID(f ile,field, iref)
	12626	0
	12627
	12628	$$GETSTAT^ XTID(): Ge t Status I nformation (Term/Con cept)
	12629	Reference Type:Suppo rted
	12630	Category:T oolkit—VHA Unique ID (VUID)
	12631	ICR #:4631
	12632	Descriptio n:This ext rinsic fun ction retr ieves the status inf ormation f or a given term/conc ept refere nce and a specified date/time.
	12633	Format:$$G ETSTAT^XTI D(file[,fi eld],iref[ ,datetime] )
	12634	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12635	field:(opt ional) Fie ld number, in the “f ile” input parameter where ter m/concept is defined .
	12636	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r, and it represents terms def ined in th e file “fi le” input parameter.
	12637	Defined:
	12638	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12639	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12640	iref:(requ ired) Inte rnal refer ence for t erm/concep t.
	12641	File entri es—This is an IENS. For exampl e:
	12642	iref = “5, ”
	12643	SETS OF CO DES—This i s the inte rnal value of the co de. For ex ample:
	12644	iref = 3 o riref = “f ” oriref = “M”
	12645	datetime:( optional) VA FileMan date/time . It defau lts to NOW .
	12646	Output:ret urns:Retur ns results of operat ion as fol lows:
	12647	Successful —<internal value>^<V A FileMan effective date/time> ^<external value>For example:
	12648	0^3050220. 115720^INA CTIVE1^305 0225.11571 1^ACTIVE
	12649	Unsuccessf ul—^<error message>
	12650	NOTE: The first piec e is empty . This dif ferentiate s it from the succes sful case, where the first pie ce is eith er 0 or 1.
	12651
	12652	Examples
	12653	Example 1
	12654	For terms defined in fields th at are SET OF CODES:
	12655	>S file=2, field=.02, iref=“M”,d atetime=$$ NOW^XLFDT
	12656	>W $$GETST AT^XTID(fi le,field,i ref,dateti me)
	12657	1^3050121. 154752^ACT IVE
	12658
	12659	Example 2
	12660	For terms defined in a single file:
	12661	>S file=16 000009,fie ld=.01,ire f=“3,”,dat etime=“”
	12662	>W $$GETST AT^XTID(fi le,field,i ref,dateti me)
	12663	0^3050122. 154755^INA CTIVE
	12664
	12665	$$GETVUID^ XTID(): Ge t VUID (Te rm/Concept )
	12666	Reference Type:Suppo rted
	12667	Category:T oolkit—VHA Unique ID (VUID)
	12668	ICR #:4631
	12669	Descriptio n:This ext rinsic fun ction retr ieves the VHA Unique ID (VUID) for a giv en term/co ncept refe rence.
	12670	Format:$$G ETVUID^XTI D(file[,fi eld],iref)
	12671	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12672	field:(opt ional) Fie ld number in the “fi le” input parameter where term /concept i s defined.
	12673	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r, and it represents terms def ined in th e file ent ered in th e “file” i nput param eter.
	12674	Defined:
	12675	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12676	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12677	iref:(requ ired) Inte rnal refer ence for t erm/concep t:
	12678	File Entri es—This is an IENS. For exampl e:
	12679	iref=“5,”
	12680	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:
	12681	iref = 3 o riref = “f ” oriref = “M”
	12682	Output:ret urns:Retur ns results of operat ion as fol lows:
	12683	Successful —VHA Uniqu e ID (VUID )
	12684	Unsuccessf ul—0^<erro r message>
	12685
	12686	Examples
	12687	Example 1
	12688	For terms defined in fields th at are SET OF CODES:
	12689	>S file=2, field=.02, iref=“M”
	12690	>W $$GETVU ID^XTID(fi le,field,i ref)
	12691	123456
	12692
	12693	Example 2
	12694	For terms defined in a single file:
	12695	>S file=16 000009,fie ld=.01,ire f=“3,”
	12696	>W $$GETVU ID^XTID(fi le,field,i ref)
	12697	123457
	12698
	12699	$$SCREEN^X TID(): Get Screening Condition (Term/Con cept)
	12700	Reference Type:Suppo rted
	12701	Category:T oolkit—VHA Unique ID (VUID)
	12702	ICR #:4631
	12703	Descriptio n:As of Ke rnel Toolk it patch X T7.3108, this extr insic func tion retri eves the s creening c ondition f or a given term/conc ept refere nce and sp ecified da te/time. I t returns whether or not a giv en entry s hould be s creened ou t of selec tion lists . This API should no t be used to determi ne if the given entr y is activ e/inactive , since th e API take s into con sideration where in the standa rdization process th e facility is. It re turns the following values:
	12704	0—If the g iven entry is select able (i.e. , “do not screen it out”).
	12705	1—If the e ntry is no t selectab le (i.e., “screen it out”).
	12706	Format:$$S CREEN^XTID (file[,fie ld],iref[, datetime][ ,.cached])
	12707	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12708	field:(opt ional) Fie ld number, in the “f ile” input parameter where ter m/concept is defined .
	12709	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r, and it represents terms def ined in th e file ent ered in th e “file” i nput param eter.
	12710	Defined:
	12711	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12712	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12713	iref:(requ ired) Inte rnal refer ence for t erm/concep t:
	12714	File entri es—This is an IENS. For exampl e:
	12715	iref = “5, ”
	12716	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:
	12717	iref = 3 o riref = “f ” oriref = “M”
	12718	datetime:( optional) VA FileMan date/time against w hich scree ning is ch ecked. It defaults t o NOW.
	12719	NOTE: If t he value o f the date time param eter conta ins a date and no ti me, no ent ries are r eturned fo r the firs t day.
	12720	.cached:(o ptional) F lag to ind icate cach ing. Used mainly whe n defining the “scre en” parame ter [e.g., DIC(“S”)] while sea rching lar ge files. This impro ves the sp eed of the search.
	12721	NOTE: It m ust be KIL Led before initiatin g each sea rch query (e.g., bef ore callin g the ^DIC ).
	12722	Output:ret urns:Retur ns the scr eening con dition as follows:
	12723	0—When ter m/concept is selecta ble (i.e., do not sc reen it ou t).
	12724	1—When ter m/concept is not sel ectable (i .e., scree n it out).
	12725
	12726	Examples
	12727	Example 1
	12728	For terms defined in fields th at are SET OF CODES:
	12729	>S file=2, field=.02, iref=“M”,d atetime=$$ NOW^XLFDT
	12730	>W $$SCREE N^XTID(fil e,field,ir ef,datetim e)
	12731	0
	12732
	12733	Example 2
	12734	For terms defined in a single file:
	12735	>S file=16 000009,fie ld=.01,ire f=“3,”,dat etime=“”
	12736	>W $$SCREE N^XTID(fil e,field,ir ef,datetim e)
	12737	0
	12738
	12739	Example 3
	12740	When searc hing a lar ge file:
	12741	>S file=12 0.52,field =.01,datet ime=“”
	12742	>S SCREEN= “I ‘$$SCRE EN^XTID(fi le,field,Y _”“,”“,dat etime,.cac hed)”
	12743	>. . .
	12744	>K cached
	12745	>D LIST^DI C(file,,“. 01;99.99”, ,“*”,,,,SC REEN,,“LIS T”,“MSG”)
	12746	>K cached
	12747
	12748	$$SETMASTR ^XTID(): S et Master VUID Flag (Term/Conc ept)
	12749	Reference Type:Suppo rted
	12750	Category:T oolkit—VHA Unique ID (VUID)
	12751	ICR #:4631
	12752	Descriptio n:This ext rinsic fun ction stor es (sets) the value of the MAS TER ENTRY FOR VUID f lag for a given term /concept r eference. The MASTER ENTRY FOR VUID flag distingui shes refer ences that might be duplicates .
	12753	Format:$$S ETMASTR^XT ID(file[,f ield],iref ,mstrflag)
	12754	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12755	field:(opt ional) Fie ld number in the “fi le” input parameter where term /concept i s defined.
	12756	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r. It repr esents the terms def ined in th e file ent ered in th e “file” i nput param eter.
	12757	Defined:
	12758	Entered as .01; it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12759	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12760	iref:(requ ired) Inte rnal refer ence for t erm/concep t:
	12761	File Entri es—This is an IENS. For exampl e:
	12762	iref=“5,”
	12763	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:
	12764	iref = 3 o riref = “f ” oriref = “M”
	12765	mstrflag:( required) The intern al value o f the MAST ER ENTRY F OR VUID fi eld. Possi ble values are as fo llows:
	12766	0—NO.
	12767	1—YES.
	12768	Output:ret urns:Retur ns results of operat ion as fol lows:
	12769	Successful —1
	12770	Unsuccessf ul—0^<erro r message>
	12771
	12772	Examples
	12773	Example 1
	12774	For terms defined in fields th at are SET OF CODES:
	12775	>S file=2, field=.02, iref=“M”,m strflag=0
	12776	>W $$SETMA STR^XTID(f ile,field, iref,mstrf lag)
	12777	1
	12778
	12779	Example 2
	12780	For terms defined in a single file:
	12781	>S file=16 000009,fie ld=.01,ire f=“3,”,mst rflag=1
	12782	>W $$SETMA STR^XTID(f ile,field, iref,mstrf lag)
	12783	1
	12784
	12785	Example 3
	12786	>S file=16 000009,fie ld=.01,ire f=“6,”,mst rflag=1
	12787	>W $$SETMA STR^XTID(f ile,field, iref,mstrf lag)
	12788	0^pre-exis ting maste r entry
	12789
	12790	$$SETSTAT^ XTID(): Se t Status I nformation (Term/Con cept)
	12791	Reference Type:Suppo rted
	12792	Category:T oolkit—VHA Unique ID (VUID)
	12793	ICR #:4631
	12794	Descriptio n:This ext rinsic fun ction stor es (sets) the status and effec tive date/ time for t he given t erm/concep t.
	12795	Format:$$S ETSTAT^XTI D(file[,fi eld],iref, status[,da tetime])
	12796	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12797	field:(opt ional) Fie ld number in the “fi le” input parameter where term /concept i s defined.
	12798	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r, and it represents terms def ined in th e file ent ered in th e “file” i nput param eter.
	12799	Defined:
	12800	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12801	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12802	iref:(requ ired) Inte rnal refer ence for t erm/concep t:
	12803	File entri es—This is an IENS. For exampl e:
	12804	iref = “5, ”
	12805	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:
	12806	iref = 3 o riref = “f ” oriref = “M”
	12807	status:(re quired) Th e status i nternal va lue. Possi ble values are as fo llows:
	12808	0—INACTIVE .
	12809	1—ACTIVE.
	12810	datetime:( optional) VA FileMan date/time . It defau lts to NOW .
	12811	Output:ret urns:Retur ns results of operat ion as fol lows:
	12812	Successful —1
	12813	Unsuccessf ul—0^<erro r message>
	12814
	12815	Examples
	12816	Example 1
	12817	For terms defined in fields th at are SET OF CODES:
	12818	>S file=2, field=.02, iref=“M”,s tatus=1,da tetime=$$N OW^XLFDT
	12819	>W $$SETST AT^XTID(fi le,field,i ref,status ,datetime)
	12820	1
	12821
	12822	Example 2
	12823	For terms defined in a single file:
	12824	>S file=16 000009,fie ld=.01,ire f=“3,”,sta tus=1,date time=$$NOW ^XLFDT
	12825	>W $$SETST AT^XTID(fi le,field,i ref,status ,datetime)
	12826	1
	12827
	12828	$$SETVUID^ XTID(): Se t VUID (Te rm/Concept )
	12829	Reference Type:Suppo rted
	12830	Category:T oolkit—VHA Unique ID (VUID)
	12831	ICR #:4631
	12832	Descriptio n:This ext rinsic fun ction popu lates (set s) the VHA Unique ID (VUID) fo r a given term/conce pt referen ce.
	12833	It also au tomaticall y sets the MASTER EN TRY FOR VU ID field t o distingu ish refere nces that might be d uplicates. If this i s the firs t referenc e assigned the VUID, it sets t he MASTER ENTRY FOR VUID equal to 1. If another en try alread y has the given VUID , it sets the MASTER ENTRY FOR VUID equa l to 0.
	12834	Format:$$S ETVUID^XTI D(file[,fi eld],iref, vuid)
	12835	Input Para meters:fil e:(require d) VistA f ile/subfil e number w here term/ concept is defined.
	12836	field:(opt ional) Fie ld number in the “fi le” input parameter where term /concept i s defined.
	12837	Not Define d—If not d efined, th is field d efaults to the .01 f ield numbe r, and it represents terms def ined in th e file ent ered in th e “file” i nput param eter.
	12838	Defined:
	12839	Entered as .01, it r epresents the terms defined in the file entered in the “file ” input pa rameter.
	12840	Otherwise, the field number en tered must be a SET OF CODES d ata type f ield in th e file ent ered in th e “file” i nput param eter.
	12841	iref:(requ ired) Inte rnal refer ence for t erm/concep t.
	12842	File entri es—This is an IENS. For exampl e:
	12843	iref = “5”
	12844	SET OF COD ES—This is the inter nal value of the cod e. For exa mple:
	12845	iref = 3 o riref = “f ” oriref = “M”
	12846	vuid:(requ ired) The VHA Unique ID (VUID) to assign the given term/conc ept refere nce.
	12847	Output:ret urns:Retur ns results of operat ion as fol lows:
	12848	Successful —1
	12849	Unsuccessf ul—0^<erro r message>
	12850
	12851	Examples
	12852	Example 1
	12853	For terms defined in fields th at are SET OF CODES:
	12854	>S file=2, field=.02, iref=“M”,v uid=123456
	12855	>W $$SETVU ID^XTID(fi le,field,i ref,vuid)
	12856	1
	12857
	12858	Example 2
	12859	For terms defined in a single file:
	12860	>S file=16 000009,fie ld=.01,ire f=“3,”,vui d=123457
	12861	>W $$SETVU ID^XTID(fi le,field,i ref,vuid)
	12862	1
	12863
	12864	Toolkit—Ro utine Tool s
	12865	Kernel Too lkit provi des develo per utilit ies for wo rking with M routine s and glob als. This section de scribes th e routine tools expo rted with Kernel Too lkit. Thes e tools ar e useful t o system a dministrat ors and Vi stA softwa re develop ers.
	12866	Direct Mod e Utilitie s
	12867	Several Ke rnel Toolk it direct mode utili ties are a vailable f or develop ers to use at the M prompt, us ually invo lving the DO command . They are not APIs and cannot be used i n software applicati on routine s.
	12868	Table 34: Routine To ols—Direct Mode Util ities
	12869	Direct Mod e Utility
	12870	Descriptio n
	12871	>D ^XTFCR
	12872	Generate a flow char t of an en tire routi ne.
	12873	>D ^XTFCE
	12874	Generate a flow char t of the p rocessing performed from a spe cified ent ry point t o the term ination of processin g resultin g from tha t entry po int.
	12875	>D ^%INDEX
	12876	(obsolete) To run %I NDEX.
	12877	>D ^XINDEX
	12878	To run XIN DEX.
	12879	>X ^%Z
	12880	Invokes th e ^%Z edit or.
	12881	>D ^XTRGRP E
	12882	Edit a gro up of rout ines.
	12883	>D ^XTVCHG
	12884	Changes al l occurren ces of one variable to another .
	12885	>D ^XTVNUM
	12886	Update or set the ve rsion numb er into a set of rou tines.
	12887	>D ^%ZTP1
	12888	A summary listing of the first , and opti onally the second, l ine of one or more r outines ca n be obtai ned.
	12889	>D ^%ZTPP
	12890	Print a li sting of e ntire rout ines.
	12891	>D ^XTRCMP
	12892	Compare tw o routines with diff erent name s and disp lay the di fferences (using Mai lMan’s Pac kMan compa re utiliti es).
	12893	>D TAPE^XT RCMP
	12894	Compares r outines in a Host Fi le Server (HFS) file to an ins talled rou tine and d isplays th e differen ces.
	12895	NOTE: Whi le it is s till calle d a “TAPE” compare, it is actu ally compa ring a rou tine in an HFS file to an inst alled rout ine.
	12896	>D ^%ZTRDE L
	12897	Delete one or more r outines.
	12898	>D ^%RR (O S-specific )
	12899	Loads rout ines from an externa l device, such as ma gtape.
	12900	>D ^%RS (O S-specific )
	12901	Output rou tines to a n external device, s uch as a m agtape.
	12902
	12903	Routine To ols Menu
	12904	Most of th ese tools are availa ble as opt ions on th e Routine Tools menu [XUPR-ROU TINE-TOOLS ] located on the Pro grammer Op tions menu [XUPROG], which is locked wit h the XUPR OG securit y key. Som e subordin ate menu o ptions are locked wi th the XUP ROGMODE or XUPROG se curity key s as an ex tra level of securit y.
	12905	Routines c an be edit ed, analyz ed by flow -charting, printed, compared, deleted, a nd moved b y using an option or its corre sponding d irect mode utility.
	12906	The Routin e Tools me nu is show n in Figur e 129:
	12907	Figure 129 : Routine Tools—Menu options
	12908	SYSTEMS MA NAGER MENU ... [EVE]
	12909	Programm er Options ... <lock ed with XU PROG>[XUPR OG]
	12910	Routine Tools ... [XUPR-ROU TINE-TOOLS ]
	12911	%Inde x of Routi nes[XUINDE X]
	12912	Compa re local/n ational ch ecksums re port[XU CH ECKSUM REP ORT]
	12913	Compa re routine s on tape to disk[XU PR-RTN-TAP E-CMP]
	12914	Compa re two rou tines[XT-R OUTINE COM PARE]
	12915	Delet e Routines <locked w ith XUPROG MODE>[XTRD EL]
	12916	Flow Chart Enti re Routine [XTFCR]
	12917	Flow Chart from Entry Poi nt[XTFCE]
	12918	Group Routine E dit <locke d with XUP ROGMODE>[X TRGRPE]
	12919	Input routines <locked wi th XUPROG> [XUROUTINE IN]
	12920	List Routines[X UPRROU]
	12921	Load/ refresh ch ecksum val ues into R OUTINE fil e[XU CHECK SUM LOAD]
	12922	Outpu t routines [XUROUTINE OUT]
	12923	Routi ne Edit <l ocked with XUPROGMOD E>[XUPR RT N EDIT]
	12924	Routi nes by Pat ch Number[ XUPR RTN P ATCH]
	12925	Varia ble change r <locked with XUPRO GMODE>[XT- VARIABLE C HANGER]
	12926	Versi on Number Update <lo cked with XUPROGMODE >[XT-VERSI ON NUMBER]
	12927
	12928	These opti ons are do cumented i n the sect ions that follow, gr ouped by r outine typ e.
	12929	Analyzing Routines
	12930	%Index of Routines O ption—XIND EX
	12931	The %Index of Routin es option [XUINDEX] calls Kern el Toolkit ’s XINDEX utility (f ormerly kn own as %IN DEX utilit y). XINDEX is a stat ic analysi s tool tha t plays th e dual rol e of a Vis tA-aware c ross-refer encing too l and a co de checker (or recog nizer).
	12932	As of Kern el Toolkit patch XT* 7.3*132, t he %Index of Routine s option [ XUINDEX] a llows user s to check the conte nts of any of the fo llowing:
	12933	Routines—X INDEX chec ks the spe cified rou tines (e.g ., XU*).
	12934	Builds—XIN DEX checks the conte nts of the specified build def ined in th e BUILD fi le (#9.6). XINDEX ch ecks all c omponents of the bui ld on the current sy stem, whic h includes , routines , options, templates , data dic tionaries, etc.
	12935	Installs—X INDEX chec ks the con tents of t he specifi ed install defined i n the INST ALL file ( #9.7). XIN DEX checks all compo nents of t he install that have temporari ly been lo aded into ^XTEMP glo bal, which includes, routines, options, templates, data dict ionaries, etc.
	12936	Packages—X INDEX chec ks the con tents of t he specifi ed package defined i n the PACK AGE file ( #9.4). XIN DEX checks all compo nents of t he package on the cu rrent syst em, which includes, routines, options, t emplates, data dicti onaries, e tc.
	12937	Figure 130 : %Index o f Routines option—Sa mple user entries
	12938	Select Rou tine Tools Option: % INDEX <Ent er> of Rou tines
	12939
	12940	V . A. C R O S S R E F E R E N C E R 7. 3
	12941	[2008 V A Standard s & Conven tions]
	12942	U CI: KRN CP U: KRN Dec 13, 20 11@07:40:4 4
	12943
	12944	All Routin es? No => NO
	12945
	12946	Routine: H LUOPT
	12947	Routine: < Enter>
	12948	1 routine
	12949
	12950
	12951	As of Kern el Toolkit patch XT* 7.3*132: C hoose 1 of these 3 o ptions and skip the other prom pts.
	12952	As of Kern el Toolkit patch XT* 7.3*132: C hoose 1 of these 3 o ptions and skip the other prom pts.
	12953	Select BUI LD NAME: < Enter>
	12954	Select INS TALL NAME: <Enter>
	12955	Select PAC KAGE NAME: <Enter>
	12956
	12957	Print more than comp iled error s and warn ings? YES/ / <Enter>
	12958
	12959	Print summ ary only? NO// <Ente r>
	12960
	12961	Print rout ines? YES/ / <Enter>
	12962
	12963
	12964	Or enter “ S” for an indented r eport.
	12965	Or enter “ S” for an indented r eport.
	12966	Print (R)e gular,(S)t ructured o r (B)oth? R// <Ente r>
	12967
	12968	Print erro rs and war nings with each rout ine? YES// <Enter>
	12969
	12970
	12971	Or enter Y ES to stor e the para meters.
	12972	Or enter Y ES to stor e the para meters.
	12973	Save param eters in R OUTINE fil e? NO// <E nter>
	12974
	12975	Index all called rou tines? NO/ / <Enter>
	12976	DEVICE: <E nter> Tel net Termin al Righ t Margin: 80// <Ente r>
	12977
	12978	V . A. C R O S S R E F E R E N C E R 7. 3
	12979	[2008 V A Standard s & Conven tions]
	12980	U CI: KRN CP U: KRN Dec 13, 20 11@07:40:4 4
	12981	Routines: 1 Faux Ro utines: 0
	12982
	12983	HLUOPT
	12984
	12985	--- CROSS REFERENCIN G ---
	12986
	12987	Press r eturn to c ontinue: < Enter>
	12988
	12989
	12990
	12991	After pres sing Enter , the opti on display s the sele cted routi ne (only t he first t wo lines i ncluded he re).
	12992	After pres sing Enter , the opti on display s the sele cted routi ne (only t he first t wo lines i ncluded he re).
	12993	Compiled l ist of Err ors and Wa rnings Dec 13, 20 11@07:40:4 4 page 1
	12994
	12995	HLUOPT * * 69 Lin es, 3758 Bytes, Che cksum: B18 177059
	12996
	12997
	12998	Warning er ror messag e is displ ayed for t his routin e.
	12999	Warning er ror messag e is displ ayed for t his routin e.
	13000
	13001	HOLD+4 W - Nul l line (no commands or comment ).
	13002
	13003	--- Routin e Detail --- with REGULAR RO UTINE LIST ING ---
	13004	Press r eturn to c ontinue:
	13005	<Enter>
	13006
	13007	HLUOPT * * 69 Lin es, 3758 Bytes, Che cksum: B18 177059
	13008	Dec 13, 20 11@07:40:4 4 page 2
	13009	548 by tes in com ments
	13010	HLUOPT ; AISC/SAW-M ain Menu f or HL7 Mod ule ;07/26 /99 08:47
	13011	; ;1.6;HEALT H LEVEL SE VEN;57 ;Oct 13, 1 995
	13012
	13013	REF: For m ore inform ation on t he XINDEX utility, s ee the “XI NDEX” sect ion.
	13014	Flow Chart Entire Ro utine Opti on
	13015	The Flow C hart Entir e Routine option [XT FCR] gener ates a flo w chart, s howing the processin g performe d within a n entire r outine.
	13016	The follow ing corres ponding di rect mode utility ca n be used in program mer mode:
	13017	>D ^XTFCR
	13018	Flow Chart From Entr y Point Op tion
	13019	The Flow C hart from Entry Poin t option [ XTFCE] gen erates a f low chart of the pro cessing pe rformed fr om a speci fied entry point to its termin ation of p rocessing. It also a llows the user to ex pand the c ode in oth er routine s or entry points re ferenced b y DO or GO TO command s.
	13020	The follow ing corres ponding di rect mode utility ca n be used in program mer mode:
	13021	>D ^XTFCE
	13022	Editing Ro utines
	13023	Group Rout ine Edit O ption
	13024	The Group Routine Ed it option [XTRGRPE] calls the XTRGRPE ro utine to e dit a grou p of routi nes. Once several ro utines are identifie d, the Ker nel Toolki t ^%Z edit or is call ed. This o ption is l ocked with XUPROGMOD E.
	13025	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13026	>D ^XTRGRP E
	13027	Routine Ed it Option
	13028	The Routin e Edit opt ion [XUPR RTN EDIT] invokes th e ^%Z edit or. The ^% Z editor c an be used to edit a group of routines w ith the Gr oup Routin e Edit opt ion. This allows dev elopers at an extern al site (e .g., on th e site man ager’s sta ff) to edi t M routin es. This o ption is l ocked with the XUPRO GMODE secu rity key.
	13029	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13030	>X ^%Z
	13031	REF: For m ore inform ation on t he ^%Z Edi tor, see t he “^%Z Ed itor” sect ion in Sec tion 17, “ Miscellane ous: Devel oper Tools .”
	13032	Routines b y Patch Nu mber Optio n
	13033	The Routin es by Patc h Number o ption [XUP R RTN PATC H] allows users to p rint routi nes associ ated with a patch. W hen prompt ed, enter a list of routines. The output is sorted by patch number.
	13034	Variable C hanger Opt ion
	13035	The Variab le Changer option [X T-VARIABLE CHANGER] runs the X TVCHG rout ine, which changes a ll occurre nces of on e variable to anothe r. This op tion is lo cked with the XUPROG MODE secur ity key.
	13036	CAUTION: T his option changes D Os and GOT Os also, b ut it does not chang e the targ et of the DOs and GO TOs. For e xample, if you reque st to chan ge all occ urrences o f “TAG” to “TAGS”, “ DO TAG” wo uld be cha nged to “D O TAGS”. H owever, th e actual L ine Label called TAG would not be change d.
	13037	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13038	>D ^XTVCHG
	13039	Version Nu mber Updat e Option
	13040	The Versio n Number U pdate opti on [XT-VER SION NUMBE R] updates version n umbers of one or mor e routines . This opt ion runs t he XTVNUM routine to update or set the v ersion num ber into a set of ro utines. Th is option is locked with the X UPROGMODE security k ey.
	13041	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13042	>D ^XTVNUM
	13043	Printing R outines
	13044	List Routi nes Option
	13045	The List R outines op tion [XUPR ROU] uses the %ZTPP utility to print a l isting of entire rou tines.
	13046	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13047	>D ^%ZTPP
	13048	Comparing Routines
	13049	Compare lo cal/nation al checksu ms report Option
	13050	The Compar e local/na tional che cksums rep ort option [XU CHECK SUM REPORT ] compares checksums for routi nes to the values in the ROUTI NE file (# 9.8). It p roduces a report lis ting routi nes that d iffer by t he followi ng criteri a:
	13051	Patch or v ersion, wh ere the ve rsion or p atch may b e correct but checks ums are of f
	13052	Local rout ines being tracked
	13053	Informatio n is not o n record f or a patch (e.g., te st patches )
	13054	Nationally released routine ch ecksums ar e sent by Master Fil e Updates to the loc al ROUTINE file (#9. 8) automat ically. Lo cal sites may also r ecord chec ksums in t he CHECKSU M VALUE fi eld in the ROUTINE f ile (#9.8) . To compa re local r outines th at are bei ng tracked , the CHEC KSUM REPOR T field sh ould be se t to “Loca l – report .”
	13055	As of Kern el patch X U8.0369, the integ rity check ing CHECK1 ^XTSUMBLD routine su pports the Compare l ocal/natio nal checks ums report option [X U CHECKSUM REPORT].
	13056	As of Kern el patch X U8.0393, KIDS was modified t o send a m essage to a server o n FORUM wh en a KIDS build is s ent to a H ost File S erver (HFS ) device. This messa ge contain s the chec ksums for the routin es in the patch. The server on FORUM mat ches the m essage wit h a patch if the sen ding domai n is autho rized on F ORUM. Ther e is no lo nger a nee d for deve lopers to manually i nclude rou tine check sums (eith er CHECK^X TSUMBLD or CHECK1^XT SUMBLD rou tines) in the patch descriptio n. The pat ch module includes t he before and after CHECK1^XTS UMBLD valu es in the Routine In formation section at the end o f the patc h document .
	13057	With chang es in the National P atch Modul e (NPM) on FORUM, wh en the pat ch is rele ased the c hecksums f or the rou tines are moved to t he ROUTINE file (#9. 8) on FORU M. The che cksum “bef ore” value s come fro m the FORU M ROUTINE file (#9.8 ) and are considered the GOLD standard f or release d checksum s. The loc al site’s Compare lo cal/nation al checksu ms report option [XU CHECKSUM REPORT] us es the FOR UM ROUTINE file (#9. 8) as its source to create rep orts showi ng any rou tines that do not ma tch.
	13058	This patch also modi fied the K IDS BUILD file (#9.6 ) by addin g the TRAN SPORT BUIL D NUMBER f ield (#63) used to s tore a bui ld number that is in cremented each time a build is made. Thi s build nu mber is ad ded to the second li ne of each routine i n the 7th “;” piece. This make s it easy to tell if a site is running t he current release d uring test ing and af terword. T he leading “B” found in the ch ecksum tel ls the cod e what che cksum API to use.
	13059	Compare Ro utines on Tape to Di sk Option
	13060	The Compar e Routines on Tape t o Disk opt ion [XUPR- RTN-TAPE-C MP] compar es routine s and disp lays the d ifferences . This opt ion reads a standard Caché %RO Host File Server (H FS) file a nd compare s the rout ines on th e HFS file with a ro utine with the same name in th e current account.
	13061	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13062	>D TE^XTRC MP
	13063	NOTE: Whil e it is st ill called a “TAPE” compare, i t is actua lly compar ing a rout ine in a H ost File S erver (HFS ) file to an install ed routine .
	13064	Compare Tw o Routines Option
	13065	The Compar e Two Rout ines optio n [XT-ROUT INE COMPAR E] compare s two rout ines with different names that are locat ed in the same accou nt and dis plays/prin ts the dif ferences ( using Mail Man’s Pack Man compar e utilitie s).
	13066	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13067	>D ^XTRCMP
	13068	Deleting R outines
	13069	Delete Rou tines Opti on
	13070	The Delete Routines option [XT RDEL] can be used to delete on e or more routine(s) . The wild card synta x can be u sed to del ete a set, such as A BC* to del ete all th ose routin es beginni ng with th e letters ABC. This option is locked wit h the XUPR OGMODE sec urity key.
	13071	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13072	>D ^%ZTRDE L
	13073	Load and S ave Routin es
	13074	The Input Routines a nd Output Routines o ptions can be used t o move rou tines from one UCI t o another. These mak e use of o perating s ystem-spec ific utili ties such as %RR for routine r estore and %RS for r outine sav e.
	13075	Input Rout ines Optio n
	13076	The Input Routines o ption [XUR OUTINE IN] loads rou tines from an extern al device. This opti on is lock ed with th e XUPROG s ecurity ke y.
	13077	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13078	>D ^%RR (O S-specific )
	13079	Output Rou tines Opti on
	13080	The Output Routines option [XU ROUTINE OU T] outputs routines to an exte rnal devic e, such as a host fi le.
	13081	The corres ponding di rect mode utility ca n be used in program mer mode a s follows:
	13082	>D ^%RS (O S-specific )
	13083	Load/refre sh checksu m values i nto ROUTIN E file Opt ion
	13084	The Load/r efresh che cksum valu es into RO UTINE file option [X U CHECKSUM LOAD] can be used t o update t he ROUTINE file (#9. 8) with th e latest c hecksum va lues from FORUM.
	13085	REF: Kerne l Toolkit Applicatio n Programm ing Interf aces (APIs ) are docu mented in the “Toolk it: Develo per Tools” section i n the Kern el Develop er’s Guide . Kernel a nd Kernel Toolkit AP Is are als o availabl e in HTML format on the VA Int ranet Webs ite.
	13086	Toolkit—Ve rification Tools
	13087	Kernel Too lkit provi des an App lication P rogramming Interface (API) tha t includes developer utilities for worki ng with ro utines and globals. This secti on describ es the ver ification tools expo rted with Kernel Too lkit that are useful to system administr ators and developers for revie wing Veter ans Health Informati on Systems and Techn ology Arch itecture ( VistA) sof tware.
	13088	Verificati on tools c an be acce ssed throu gh one of three meth ods:
	13089	Direct Mod e Utilitie s
	13090	Programmer Options M enu
	13091	Operations Managemen t Menu
	13092	Direct Mod e Utilitie s
	13093	Several Ke rnel Toolk it direct mode utili ties are a vailable f or develop ers to use at the M prompt, us ually invo lving the DO command . They are not APIs and cannot be used i n software applicati on routine s. These d irect mode utilities are descr ibed below by catego ry.
	13094	The XINDEX utility c an be used to check a routine or set of routines a gainst sta ndards suc h as the 1 995 ANSI M Standard syntax and VA Progra mming Stan dards and Convention s (SAC).
	13095	REF: For m ore inform ation on t he XINDEX utility, s ee the “%I ndex of Ro utines Opt ion” secti on in the “Toolkit—R outine Too ls” sectio n in this section.
	13096	The corres ponding di rect mode utility ca n be used in Program mer mode:
	13097	>D ^XINDEX
	13098	Many of th e options on the Pro grammer Op tions menu can also be run as direct mod e utilitie s. Some ar e not avai lable as o ptions, bu t only as direct mod e utilitie s callable at the M prompt. Ta ble 35 lis ts example s on how t o run thes e utilitie s when wor king in Pr ogrammer m ode.
	13099	Table 35: Verificati on Tools—D irect Mode Utilities
	13100	Direct Mod e Utility
	13101	Descriptio n
	13102	>D CHCKSUM ^XTSUMBLD
	13103	Check the checksum v alue of a routine at any given time.
	13104	This direc t mode uti lity allow s the deve loper to c hoose from the old C HECK^XTSUM BLD checks um routine or the ne w and more accurate CHECK1^XTS UMBLD chec ksum routi ne.
	13105	REF: For more infor mation on the CHECK^ XTSUMBLD a nd CHECK1^ XTSUMBLD r outines, s ee Section s 23 and 2 4 in the K ernel Syst ems Manage ment Guide .
	13106	>D ^nsNTEG
	13107	Check Inte grity of n amespace ( ns) Packag e. For exa mple, D ^X TNTEG comp ares the K ernel Tool kit namesp ace (XT) c hecksums w ith expect ed values.
	13108	>D ONE^nsN TEG
	13109	Check Inte grity Rout ine in nam espace (ns ) Package.
	13110	>D ^%ZTER
	13111	Record an Error.
	13112	>D ^XTER
	13113	Display Er ror Trap.
	13114	>D ^XTERPU R
	13115	Purge Erro r Log.
	13116	>D ^%INDEX
	13117	(obsolete) To run %I NDEX.
	13118	>D ^XINDEX
	13119	To run XIN DEX. XINDE X is simil ar to %IND EX but sup ports the most curre nt M stand ard.
	13120
	13121	NOTE: For informatio n on the o ptions ass ociated wi th the rou tines asso ciated wit h these ve rification tools dir ect mode u tilities, see the “V erificatio n Tools” s ection in the “Toolk it” sectio n in the K ernel Syst ems Manage ment Guide .
	13122	Verifier T ools Menu
	13123	The Verifi er Tools M enu contai ns options that are available as tools f or verific ation duri ng program developme nt. These options ar e located on the Ver ifier Tool s Menu [XT V MENU], w hich is lo cated on t he Systems Manager M enu. These tools are useful fo r develope rs to:
	13124	Record the text of t he routine s indicate d in the f ile used t o maintain changes i n routines .
	13125	Compare on e or more current ro utines to previous v ersions.
	13126	The Verifi er Tools M enu [XTV M ENU] consi sts of the following options t hat are de scribed be low:
	13127	Figure 131 : Verifier Tools—Men u options
	13128	SYSTEMS MA NAGER MENU ...[EVE]
	13129	Verifier Tools Men u ... [XTV MENU]
	13130	Updat e with cur rent routi nes [XTVR UPDATE]
	13131	Routi ne Compare - Current with Prev ious [XTVR COMPARE]
	13132
	13133	Update wit h Current Routines O ption
	13134	The Update with Curr ent Routin es option [XTVR UPDA TE] record s the text of the ro utines ind icated in the file u sed to mai ntain chan ges in rou tines. Onl y the last version e ntered is kept intac t; previou s entries reflect on ly the cha nges in li nes added or deleted to make t he next ve rsion. Thi s option r ecords the current r outine str ucture so that it ca n be compa red with f uture vers ions of th e routine using the Routine Co mpare - Cu rrent with Previous option [XT VR COMPARE ].
	13135	After edit ing the ro utine, the Update wi th Current Routines option can again be used to st ore change s. Rather than stori ng all min or changes , the user can choos e to wait and use th e Update w ith Curren t Routines option on ly after e xtensive e dits have been made. Lines are compared and change s, includi ng inserte d or delet ed lines, are record ed. (Alter ation of t he routine ’s second line is us ually insi gnificant and is ign ored.) The Update wi th Current Routines option can be used w henever th e develope r would li ke a new “ snapshot” of the rou tine. The XTV ROUTIN E CHANGES file (#899 1) holds e ach new sn apshot as a new vers ion. This filing met hod does n ot, howeve r, alter t he actual version nu mber of th e routine itself.
	13136	Routine Co mpare - Cu rrent with Previous Option
	13137	The Routin e Compare - Current with Previ ous option [XTVR COM PARE] comp ares one o r more cur rent routi nes to pre vious vers ions. To u se the rou tine compa re utility , copies o f the sele cted routi nes must f irst be st ored in th e XTV ROUT INE CHANGE S file (#8 991), stor ed in the ^XTV(8991, global. T his is ach ieved by u se of the Update wit h Current Routines o ption [XTV R UPDATE] on the Ver ifier Tool s Menu. Ro utines can be specif ied one by one or as a group w ith the wi ldcard syn tax (e.g., XQ*). Any initializ e routines are autom atically e xcluded. D ifferences between t he current version a nd the ind icated num ber of pri or version s are note d. The use r is promp ted for th e number o f previous versions from which to begin the listin g. An enti re history or just a brief dis play of re cent modif ications c an be obta ined.
	13138	Programmer Options M enu
	13139	The Progra mmer Optio ns menu [X UPROG] com prised of the follow ing option s:
	13140	Figure 132 : Programm er Options —Menu opti ons: Toolk it verific ation tool s
	13141	SYSTEMS MA NAGER MENU ...[EVE]
	13142	Programm er Options ...[XUPRO G]
	13143	**> Lo cked with XUPROG
	13144	KIDS Ke rnel Insta llation & Distributi on System ...[XPD MA IN]
	13145	**> Locke d with XUP ROG
	13146	PG Pr ogrammer m ode[XUPROG MODE]
	13147	**> Locke d with XUP ROGMODE
	13148	Ca lculate an d Show Che cksum Valu es[XTSUMBL D-CHECK]
	13149	De lete Unref erenced Op tions[XQ U NREF’D OPT IONS]
	13150	Er ror Proces sing ...[X UERRS]
	13151	Ge neral Para meter Tool s ...[XPAR MENU TOOL S]
	13152	Gl obal Block Count[XU BLOCK COUN T]
	13153	Li st Global[ XUPRGL]
	13154	**> Locke d with XUP ROGMODE
	13155	Ro utine Tool s ...[XUPR -ROUTINE-T OOLS]
	13156	Te st an opti on not in your menu[ XT-OPTION TEST]
	13157	**> Locke d with XUM GR
	13158
	13159	Tools foun d on the P rogrammer Options me nu that ca n be of us e for veri fication p urposes in clude:
	13160	Calculate and Show C hecksum Va lues [XTSU MBLD-CHECK ]
	13161	Error Proc essing [XU ERRS]
	13162	These opti ons are de scribed in the secti ons that f ollow.
	13163	Calculate and Show C hecksum Va lues Optio n
	13164	The Calcul ate and Sh ow Checksu m Values o ption [XTS UMBLD-CHEC K] gives d evelopers the abilit y to check the value of a rout ine at any given tim e. It does not regen erate NTEG routines and can sa fely be us ed anytime .
	13165	This optio n calls th e CHCKSUM^ XTSUMBLD d irect mode utility t o calculat e and show the check sum value for one or more rout ines in th e current account. T his value is referen ced in the Patch Mod ule descri ption for routine pa tches.
	13166	NOTE: Kern el Toolkit patch XT* 7.394, de ployed the CHECK1^XT SUMBLD rou tine and t he new log ic Checksu m: %^ZOSF( “RSUM1”). Kernel Too lkit patch XT7.3*10 0 included the CHECK 1^XTSUMBLD routine i nto the Ca lculate an d Show Che cksum Valu es option [XTSUMBLD- CHECK].
	13167	The CHECK1 ^XTSUMBLD routine is more accu rate than the old in tegrity ch ecking uti lity (CHEC K^XTSUMBLD ). CHECK1^ XTSUMBLD. It determi nes the cu rrent chec ksums for selected r outine(s), the funct ionality o f which is shown as follows:
	13168	Any commen t line wit h a single semi-colo n is presu med to be followed b y comments and only the line t ag is incl uded.
	13169	Line 2 is excluded f rom the co unt.
	13170	The total value of t he routine is determ ined (excl uding exce ptions not ed above) by multipl ying the A SCII value of each c haracter b y its posi tion on th e line and position of the lin e in the r outine bei ng checked .
	13171	The corres ponding di rect mode utility ca n be used in program mer mode:
	13172	>D CHCKSUM ^XTSUMBLD
	13173	NOTE: The integrity checking u tility CHC KSUM^XTSUM BLD suppor ts the Com pare local /national checksums report opt ion [XU CH ECKSUM REP ORT], as r eleased wi th Kernel patch XU8 .0369.
	13174	NOTE: The modificati on, CHECK1 ^XTSUMBLD, to the in tegrity ch ecking uti lity CHCKS UM^XTSUMBL D fixes th e problem in which t he old che cksum outp ut is the same check sum value, even if s ome lines were swapp ed within a routine.
	13175	Error Proc essing—Ker nel Error Trapping a nd Reporti ng
	13176	Technical personnel who have e ntered pro grammer mo de with D ^XUP, migh t choose t o record a n error en countered with D ^%Z TER. The e rror log c an be disp layed with D ^XTER, or with th e correspo nding opti on. Also, the error log can be purged wi th D ^XTER PUR. Error s can also be purged from with in the men u system w ith an opt ion that i s locked w ith the XU PROGMODE s ecurity ke y.
	13177	The corres ponding di rect mode utilities can be use d in progr ammer mode as follow s:
	13178	Record an Error:
	13179	>D ^%ZTER
	13180	Display Er ror Trap:
	13181	>D ^XTER
	13182	Purge Erro r Log:
	13183	>D ^XTERPU R
	13184	REF: For m ore inform ation on E rror Proce ssing, see Section 1 3, “Error Processing ,” in the Kernel Sys tems Manag ement Guid e.
	13185
	13186	XINDEX
	13187	Kernel Too lkit’s XIN DEX utilit y (formerl y known as %INDEX ut ility) is a static a nalysis to ol that pl ays the du al role of a VistA-a ware cross -referenci ng tool an d a code c hecker (or recognize r). As of Kernel Too lkit patch XT7.313 2, XINDEX creates a cross-refe renced lis t of globa l referenc es and rou tines invo ked by sel ecting any of the fo llowing:
	13188	Routines—X INDEX chec ks the spe cified rou tines (e.g ., XU*).
	13189	Builds—XIN DEX checks the conte nts of the specified build def ined in th e BUILD fi le (#9.6). XINDEX ch ecks all c omponents of the bui ld on the current sy stem, whic h includes , routines , options, templates , data dic tionaries, etc.
	13190	Installs—X INDEX chec ks the con tents of t he specifi ed install defined i n the INST ALL file ( #9.7). XIN DEX checks all compo nents of t he install that have temporari ly been lo aded into ^XTEMP glo bal, which includes, routines, options, templates, data dict ionaries, etc.
	13191	Packages—X INDEX chec ks the con tents of t he specifi ed package defined i n the PACK AGE file ( #9.4). XIN DEX checks all compo nents of t he package on the cu rrent syst em, which includes, routines, options, t emplates, data dicti onaries, e tc.
	13192	Use XINDEX to verify parts of a software applicati on in the VistA envi ronment th at contain M code, i ncluding t he followi ng:
	13193	Routines
	13194	Options
	13195	Compiled T emplates
	13196	Data Dicti onaries (D D)
	13197	Functions
	13198	XINDEX pro vides grea ter analys is capabil ity than o ther synta x analysis tools tha t operate at the rou tine level only. As a static a nalysis to ol, howeve r, XINDEX has a fund amental li mitation o f the type s of error s that it is able to catch and report. X INDEX is o nly able t o look at the writte n structur e of M cod e. It cann ot look at dynamic a spects, su ch as the run-time s ymbol tabl e or flow of control when it i s modified by condit ional bran ching (e.g ., through post-cond itionals o r argument indirecti on). XINDE X is also generally conservati ve, at tim es preferr ing to rep ort false positives rather tha n ignore p otential p roblems. W hen analyz ing XINDEX output, y ou must ta ke all of this into considerat ion.
	13199	VistA appl ications a re require d to follo w a set of Standards and Conve ntions (SA C) as set by the VA’ s Standard s and Conv entions Co mmittee (S ACC), whic h are defi ned as fol lows:
	13200	Standard—R equirement that must be adhere d to.
	13201	Convention —Rule that should be followed.
	13202	VistA prot ects many of its abs tractions via conven tion, even when thos e conventi ons are re quirements . XINDEX c hecks that the MUMPS (M) routi ne code co nforms to the 1995 A NSI M Stan dard and V A Programm ing Standa rds and Co nventions (SAC). XIN DEX consid ers all SA C prohibit ions as an error. XI NDEX check s SAC requ irements, because co nformance to the SAC is essent ial to the proper fu nction of VistA.
	13203	VistA is c omprised o f a number of softwa re package s (defined by namesp ace), whic h can be f urther div ided into the follow ing two ba sic groups :
	13204	Applicatio ns—VistA c lient appl ications o r applicat ion module s (e.g., P harmacy, L aboratory, Patient C are Encoun ter [PCE]) .
	13205	Infrastruc ture Appli cations—Co llection o f Infrastr ucture pac kages that implement the basic programmi ng and run time VistA framework . For exam ple:
	13206	Kernel/Ker nel Toolki t—Provides a portabl e system i nterface, a common e xecution e nvironment , and esse ntial serv ices such as signon and securi ty.
	13207	MailMan—Pr ovides Vis tA email f unctionali ty.
	13208	VA FileMan —Provides database f unctionali ty built o n top of t he M globa l subsyste m integrat ed with th e VistA se curity mod el.
	13209	It is impo rtant to r ecognize t hat the ru les for Vi stA infras tructure p ackages (p articularl y Kernel a nd VA File Man) are d ifferent f rom other VistA appl ications. Code used in infrast ructure pa ckages to implement a system i nterface m ust be abl e to use i mplementat ion-specif ic code. A ccordingly , Kernel ( and someti mes VA Fil eMan) has standing e xemptions from many of the req uirements of the SAC . Thus, XI NDEX somet imes repor ts errors and standa rds violat ions for a llowed con structs.
	13210	REF: For m ore inform ation on t he Standar ds and Con ventions C ommittee ( SACC) and Standards and Conven tions (SAC ) document ation, see the SACC VA Intrane t Website.
	13211	Types of X INDEX Find ings
	13212	XINDEX rep orts its f indings un der the fo llowing ge neral cate gories of codes (err or flags):
	13213	Table 36: XINDEX—Typ es of find ings (cate gory codes or flags)
	13214	Category C ode/Other
	13215	Descriptio n
	13216	F
	13217	Fatal M Er rors (Hard MUMPS Err or)—These are unreco verable er rors that cause a pr ogram to f ail if the commands are execut ed. It is possible, however, t hat these types of e rrors migh t exist in routines that run c orrectly. The error occurs (or may occur , dependin g on the u nderlying implementa tion) only when the errant com mands are executed.
	13218	REF: For a descript ion and sa mple code analysis o n errors i n this cat egory, see Section 2 6.13.3.1, “Fatal M E rrors (Har d MUMPS Er ror).”
	13219	W
	13220	Warning Vi olation Er rors (Acco rding to V A Conventi ons)—These are poten tial probl ems that a re not nec essarily f atal error s but most likely in dicate an error. The y require careful im plementati on.
	13221	REF: For a descript ion and sa mple code analysis o n errors i n this cat egory, see Section 2 7.12.3.2, “Warning V iolation E rrors (Acc ording to VA Convent ions).”
	13222	S
	13223	Standards Violation Errors (Ac cording to VA Standa rds)—These are issue s that do not pertai n to the M language per se, bu t rather t he require ments of t he VA Stan dards and Convention s (SAC). I ssues flag ged as Sta ndards Vio lations ca n still be syntactic ally corre ct M code that follo ws the por tability g uidelines, but does not follow the more stringent requiremen ts set for th in the SAC.
	13224	REF: For a descript ion and sa mple code analysis o n errors i n this cat egory, see Section 2 6.13.3.3, “Standards Violation Errors (A ccording t o VA Stand ards).”
	13225	I
	13226	Informatio nal Errors —These iss ues are no t necessar ily errors but still require a ttention, because th ey could i ndicate po tential pr oblems.
	13227	REF: For a descript ion and sa mple code analysis o n errors i n this cat egory, see Section 2 6.13.3.4, “Informati onal.”
	13228	Manual Che ck
	13229	Marked Ite ms Errors (Manual Ch eck)—These issues on ly apply i f a line c ontains $T EXT ($T). XINDEX rec ords the l ocation an d prints i t out unde r the “Mar ked Items” sub-heade r on the X INDEX repo rt.
	13230	REF: For a descript ion on err ors in thi s category , see Sect ion 26.13. 3.5, “Mark ed Items E rrors (Man ual Check. ”
	13231
	13232	Table 37 l ists the c urrent err or conditi ons (messa ges) that the XINDEX utility f lags. XIND EX retriev es and dis plays the messages f rom the XI NDX1 routi ne.
	13233	NOTE: Any updates (e .g., add, modify, or delete me ssages) ma de to the list of XI NDEX messa ges are ba sed on cha nges to th e XINDEX u tility via subsequen t Kernel T oolkit pat ches.
	13234	Table 37: XINDEX—Lis t of the e rror condi tions (mes sages) fla gged: Grou ped by cat egory and listed alp habeticall y); messag es are sto red in XIN DX1 routin e
	13235	Message Di splayed (c lick on li nk for mor e detail)
	13236	Category: Fatal M Er rors (Hard MUMPS Err or)
	13237	F - Bad Nu mber.
	13238	F - Bad WR ITE syntax .
	13239	F - Block structure mismatch.
	13240	F - Call t o missing label ‘lab el’ in thi s routine.
	13241	F - Call t o this lab el/routine (MISSING LABEL)
	13242	F - Comman d missing an argumen t.
	13243	F - Error in pattern code.
	13244	F - FOR Co mmand foll owed by on ly one spa ce.
	13245	F - FOR Co mmand did not contai n ‘=‘.
	13246	F - Genera l Syntax E rror.
	13247	F - GO or DO mismatc h from blo ck structu re (M45).
	13248	F - Invali d or wrong number of arguments to a func tion.
	13249	F - Label is not val id.
	13250	F - Missin g argument to a comm and post-c onditional .
	13251	F - Non-st andard (Un defined) ‘ Z’ command .
	13252	F - Quoted string no t followed by a sepa rator.
	13253	F - Refere nce to rou tine ‘^rou tine name’ . That isn ’t in this UCI.
	13254	F - UNDEFI NED COMMAN D (rest of line not checked).
	13255	NOTE: Dev elopers mu st manuall y check th ese errors .
	13256	F - Undefi ned Functi on.
	13257	F - Undefi ned Specia l Variable .
	13258	F - Unmatc hed Parent hesis.
	13259	F - Unmatc hed Quotat ion Marks.
	13260	F - Unreco gnized arg ument in S ET command .
	13261	Category: Warning Vi olation Er rors (Acco rding to V A Conventi ons)
	13262	W - Blank( s) at end of line.
	13263	W - Duplic ate label, (M57) (M standard e rror)
	13264	W - First line label NOT routi ne name.
	13265	W - Invali d global v ariable na me.
	13266	W - Invali d local va riable nam e.
	13267	W - Line c ontains a CONTROL (n on-graphic ) characte r.
	13268	W - Null l ine (no co mmands or comment).
	13269	Category: Standards Violation Errors (Ac cording to VA Standa rds)
	13270	S - $View function u sed.
	13271	S - Access to SSVN’s restricte d to Kerne l.
	13272	S - Break command us ed.
	13273	S - Extend ed referen ce.
	13274	S - First line of ro utine viol ates the S AC.
	13275	S - 2nd li ne of rout ine violat es the SAC .
	13276	S - Patch number ‘nn n’ missing from seco nd line.
	13277	S - ‘HALT’ command s hould be i nvoked thr ough ‘G ^X USCLEAN’
	13278	S - Kill o f a protec ted variab le (variab le name).
	13279	S - Kill o f an unsub scripted g lobal.
	13280	S - Unargu mented Kil l.
	13281	S - Exclus ive Kill.
	13282	S - Exclus ive or Una rgumented NEW comman d.
	13283	S - LABEL+ OFFSET syn tax
	13284	S - Line i s longer t han 245 by tes.
	13285	S - Lock m issing Tim eout.
	13286	S - Lower/ Mixed case Variable name used.
	13287	S - Lowerc ase comman d(s) used in line.
	13288	S - Non-In cremental Lock.
	13289	S - Non-st andard $Z function u sed.
	13290	S - Non-st andard $Z special va riable use d.
	13291	S - ‘OPEN’ command s hould be i nvoked thr ough ^%ZIS .
	13292	S - ‘Close ’ command should be invoked th rough ‘D ^ %ZISC’.
	13293	S - Read c ommand doe sn’t have a timeout.
	13294	S - Routin e code exc eeds SACC maximum si ze of 1500 0 (nnnnn).
	13295	S - Routin e exceeds SACC maxim um size of 20000 (nn nnn).
	13296	S - Set to a ‘%’ glo bal.
	13297	S - Should use ‘TASK MAN’ inste ad of ‘JOB ’ command.
	13298	S - View c ommand use d.
	13299	S - Violat es VA prog ramming st andards.
	13300	Category: Informatio nal Errors
	13301	I - QUIT C ommand fol lowed by o nly one sp ace.
	13302	I - Star o r pound RE AD used.
	13303
	13304	Running th e XINDEX U tility
	13305	CAUTION: W hen runnin g XINDEX t o review a n entire s oftware ap plication, it is bes t to queue the repor t for an o ff-peak ti me, since processing is intens ive.
	13306	Use either of the fo llowing me thods to c all the XI NDEX utili ty:
	13307	Direct Mod e Utility (see Figur e 134):
	13308	>D ^XINDEX
	13309	Option—Use the %Inde x of Routi nes option [XUINDEX] located o n the on t he Routine Tools men u [XUPR-RO UTINE-TOOL S] located on the Pr ogrammer O ptions men u [XUPROG] , which is locked wi th the XUP ROG securi ty key.
	13310	REF: For m ore inform ation on t he %Index of Routine s option, see the “% Index of R outines Op tion—XINDE X” section .
	13311	Figure 133 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a routi ne name on ly (1 of 3 )
	13312	KRN>D ^XIN DEX
	13313
	13314	V . A. C R O S S R E F E R E N C E R 7. 3
	13315	[2008 V A Standard s & Conven tions]
	13316	U CI: KRN CP U: KRN Jan 12, 20 12@14:47:1 6
	13317
	13318	All Routin es? No => <Enter> No
	13319
	13320	Routine: X DRMAIN
	13321	Routine: < Enter>
	13322	1 routine
	13323
	13324	Select BUI LD NAME: < Enter>
	13325	Select INS TALL NAME: <Enter>
	13326	Select PAC KAGE NAME: <Enter>
	13327
	13328	Print more than comp iled error s and warn ings? YES/ / <Enter>
	13329
	13330	Print summ ary only? NO// <Ente r>
	13331
	13332	Print rout ines? YES/ / <Enter>
	13333
	13334
	13335	Or enter “ S” for an indented r eport.
	13336	Or enter “ S” for an indented r eport.
	13337	Print (R)e gular,(S)t ructured o r (B)oth? R// <Ente r>
	13338
	13339	Print erro rs and war nings with each rout ine? YES// <Enter>
	13340
	13341
	13342	Or enter Y ES to stor e the para meters.
	13343	Or enter Y ES to stor e the para meters.
	13344	Save param eters in R OUTINE fil e? NO// <E nter>
	13345
	13346	Index all called rou tines? NO/ / <Enter>
	13347	DEVICE: ;P -OTHER <En ter> Teln et Termina l Right Margin: 2 55// 80
	13348
	13349
	13350
	13351	The XINDEX report di splays (ex cerpt).
	13352	The XINDEX report di splays (ex cerpt).
	13353	V . A. C R O S S R E F E R E N C E R 7. 3
	13354	[2008 V A Standard s & Conven tions]
	13355	U CI: KRN CP U: KRN Jan 12, 20 12@14:47:1 6
	13356	Routines: 1 Faux Ro utines: 0
	13357
	13358	XDRMAIN
	13359
	13360	--- CROSS REFERENCIN G ---
	13361
	13362	Compiled l ist of Err ors and Wa rnings Jan 12, 20 12@14:47:1 6 page 1
	13363	No errors or warning s to repor t
	13364
	13365
	13366	--- Routin e Detail --- with REGULAR RO UTINE LIST ING ---
	13367
	13368	XDRMAIN * * 80 Lin es, 3431 Bytes, Che cksum: B16 902409
	13369	Jan 12, 20 12@14:47:1 6 page 2
	13370	104 by tes in com ments
	13371	XDRMAIN ; SF-IRMFO/I HS/OHPRD/J CM - MAIN DRIVER FOR DUPLICATE MERGE SOF TWARE;
	13372	[ 08/13/92 09:50 AM ]
	13373	; ;7.3;TOOLK IT;23; r 25, 1995
	13374	; ;
	13375	START ;
	13376	S XDRMAINI= “MERGE” D ^XDRMAINI G:XDRQFLG END
	13377	F XDRMI1=0: 0 S XDRMPA IR=$O(@XDR M(“GL”)) Q :’XDRMPAIR !(XDRQFLG) S XDRMPD
	13378	A=“^VA(15, ”“OT”“,”_” “““_$P(XDR GL,U,2)_”“ ““_”,XDRMP AIR,0)” S XDRMPDA=
	13379	$O(@XDRMPD A) D MAIN D:’$D(XDRM (“NOTALK”) ) ASK
	13380	END D EOJ
	13381	Q
	13382	;
	13383	MAIN ;
	13384	S XDRMCD=$P (XDRMPAIR, U,1),XDRMC D2=$P(XDRM PAIR,U,2)
	13385	S XDRMRG(“L CK”)=“+” D LOCK^XDRU 1 K XDRMRG (“LCK”) I $D(XDRMLOC K) G MAINX
	13386	I ‘$D(XDRM( “NOVERIFY” )) S XDRMR G=0 D ^XDR MVFY G:’XD RMRG!(XDRQ FLG) MAINX
	13387	S (XDRMRG(“ FR”),XDRMA IN(“FR”))= $S($P(^VA( 15,XDRMPDA ,0),U,4)=2 :XDRMCD2,1
	13388	:XDRMCD)
	13389
	13390	.
	13391	.
	13392	.
	13393
	13394	Figure 134 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a build name (2 o f 3)
	13395	>D ^XINDEX
	13396
	13397	V . A. C R O S S R E F E R E N C E R 7. 3
	13398	[2008 V A Standard s & Conven tions]
	13399	U CI: KRN CP U: KRN Jan 12, 20 12@14:47:1 6
	13400
	13401	All Routin es? No => <Enter> N o
	13402
	13403	Routine: < Enter>
	13404	0 routines
	13405
	13406
	13407	If you spe cify a Bui ld name he re, you ar e not prom pted for a n Install or Package name.
	13408	If you spe cify a Bui ld name he re, you ar e not prom pted for a n Install or Package name.
	13409	Select BUI LD NAME: X T7.3102 <Enter> T OOLKIT
	13410	Include th e compiled template routines: N// <Enter >
	13411
	13412	Print more than comp iled error s and warn ings? YES/ / <Enter>
	13413
	13414	Print summ ary only? NO// <Ente r>
	13415
	13416	Print rout ines? YES/ / <Enter>
	13417
	13418
	13419	Or enter “ S” for an indented r eport.
	13420	Or enter “ S” for an indented r eport.
	13421	Print (R)e gular,(S)t ructured o r (B)oth? R// <Ente r>
	13422	Print the DDs, Funct ions, and Options? Y ES// <Ente r>
	13423
	13424	Print erro rs and war nings with each rout ine? YES// <Enter>
	13425
	13426
	13427	Or enter Y ES to stor e the para meters.
	13428	Or enter Y ES to stor e the para meters.
	13429	Save param eters in R OUTINE fil e? NO// <E nter>
	13430	Index all called rou tines? NO/ / <Enter>
	13431	DEVICE: ;P -OTHER <En ter> Teln et Termina l Right Margin: 2 55// 80
	13432
	13433
	13434
	13435	The XINDEX report di splays (ex cerpt).
	13436	The XINDEX report di splays (ex cerpt).
	13437	V . A. C R O S S R E F E R E N C E R 7. 3
	13438	[2008 V A Standard s & Conven tions]
	13439	U CI: KRN CP U: KRN Jan 12, 20 12@14:43:0 2
	13440
	13441	The BUILD file Data Dictionari es are bei ng process ed.
	13442
	13443	The option and funct ion files are being processed.
	13444
	13445
	13446	Routines a re being p rocessed.
	13447	Routines: 1 Faux Ro utines: 0
	13448
	13449	XTPOST
	13450
	13451	--- CROSS REFERENCIN G ---
	13452
	13453
	13454	Compiled l ist of Err ors and Wa rnings Jan 12, 20 12@14:59:5 1 page 1
	13455
	13456	XTPOST * * 106 Li nes, 3234 Bytes, Ch ecksum: B1 4328994
	13457	; ;8.0;KERNE L;102; Jul 10, 19 95
	13458	XTPOST+ 1 S - 2nd line o f routine violates t he SAC.
	13459	. S $P(^%ZRT L(3.091,0) ,U)=“RESPO NSE TIME”
	13460	CHECK+3 4 S - Set to a ‘ %’ global.
	13461	. S $P(^%ZRT L(3.091,0) ,U,2)=“3.0 91P”
	13462	CHECK+3 5 S - Set to a ‘ %’ global.
	13463	. S $P(^%ZRT L(3.092,0) ,U)=“RT DA TE_UCI,VOL ”
	13464	CHECK+3 8 S - Set to a ‘ %’ global.
	13465	. S $P(^%ZRT L(3.092,0) ,U,2)=“3.0 92”
	13466	CHECK+3 9 S - Set to a ‘ %’ global.
	13467	. S $P(^%ZRT L(3.094,0) ,U)=“RT RA WDATA”
	13468	CHECK+4 2 S - Set to a ‘ %’ global.
	13469	. S $P(^%ZRT L(3.094,0) ,U,2)=“3.0 94D”
	13470	CHECK+4 3 S - Set to a ‘ %’ global.
	13471
	13472	--- Routin e Detail --- with REGULAR RO UTINE LIST ING ---
	13473	.
	13474	.
	13475	.
	13476
	13477	Figure 135 : XINDEX—D irect mode utilities sample us er entries : Specifyi ng a packa ge name (3 of 3)
	13478	KRN>D ^XIN DEX
	13479
	13480
	13481	V . A. C R O S S R E F E R E N C E R 7. 3
	13482	[2008 V A Standard s & Conven tions]
	13483	U CI: KRN CP U: KRN Jan 12, 20 12@15:01:5 3
	13484
	13485	All Routin es? No => <Enter> No
	13486
	13487	Routine: X DRMAIN
	13488	Routine: < Enter>
	13489	1 routine< Enter>
	13490
	13491	Select BUI LD NAME: < Enter>
	13492	Select INS TALL NAME: <Enter>
	13493	Select PAC KAGE NAME: KERNEL <E nter> X U
	13494
	13495	Include th e compiled template routines: N// <Enter >
	13496
	13497	Print more than comp iled error s and warn ings? YES/ / <Enter>
	13498
	13499	Print summ ary only? NO// <Ente r>
	13500
	13501	Print rout ines? YES/ / <Enter>
	13502
	13503
	13504	Or enter “ S” for an indented r eport.
	13505	Or enter “ S” for an indented r eport.
	13506	Print (R)e gular,(S)t ructured o r (B)oth? R// <Ente r>
	13507
	13508	Print the DDs, Funct ions, and Options? Y ES// <Ente r>
	13509
	13510	Print erro rs and war nings with each rout ine? YES// <Enter>
	13511
	13512	Or enter Y ES to stor e the para meters.
	13513	Or enter Y ES to stor e the para meters.
	13514	Save param eters in R OUTINE fil e? NO// <E nter>
	13515
	13516	Index all called rou tines? NO/ / <Enter>
	13517	DEVICE: ;P -OTHER <En ter> Teln et Termina l Right Margin: 2 55// 80
	13518
	13519
	13520
	13521	The XINDEX report di splays (ex cerpt).
	13522	The XINDEX report di splays (ex cerpt).
	13523	V . A. C R O S S R E F E R E N C E R 7. 3
	13524	[2008 V A Standard s & Conven tions]
	13525	U CI: KRN CP U: KRN Jan 12, 20 12@15:01:5 3
	13526
	13527	The packag e file Dat a Dictiona ries are b eing proce ssed.
	13528
	13529	The option and funct ion files are being processed.
	13530
	13531
	13532	Routines a re being p rocessed.
	13533	Routines: 1 Faux Ro utines: 2
	13534
	13535	XDRMAIN
	13536
	13537	Data Dicti onaries
	13538	\|func \|opt
	13539
	13540	--- CROSS REFERENCIN G ---
	13541
	13542
	13543	Compiled l ist of Err ors and Wa rnings Jan 12, 20 12@15:01:5 3 page 1
	13544
	13545	\|opt * * 974 Li nes, 3594 9 Bytes, C hecksum:
	13546	I ‘$P(^VA(2 00,D0,0),U ,11),$P(^( 0),U,4)=“@ ”!($N(^(“F OF”,0))>0)
	13547	161+4 F - Undefined Function.
	13548	589+2 F - Reference to routine ‘^XUCSPRG ’. That is n’t in thi s UCI.
	13549
	13550	--- Routin e Detail --- with REGULAR RO UTINE LIST ING ---
	13551	.
	13552	.
	13553	.
	13554
	13555	Analysis o f XINDEX E rror Findi ngs by Cat egory
	13556	Fatal M Er rors (Hard MUMPS Err or)
	13557	F - Bad Nu mber
	13558	XINDEX can only chec k static n umbers in code. It d oes not ch eck the bo undaries o f the numb er, only t hat it is a legitima te number and not a string.
	13559	F - Bad WR ITE syntax
	13560	This error is usuall y a WRITE argument m isuse. The most comm on occurre nce is due to a miss ing comma after the argument.
	13561	F - Block structure mismatch
	13562	These are potentiall y one of t he most se rious type s of error s, and may lead to f atal runti me excepti ons. Howev er, examin ation of a number of routines indicates that a sig nificant n umber of t hese error s are empt y DO block s. These a re still p otential l ogic error s, but do not cause runtime ex ceptions u nder Caché . The DO c ommand, Se ction 8.2. 3 of the s tandard, d oes not se em to have a provisi on for emp ty blocks, so this i s an error .
	13563	The follow ing code e xtract fro m ENGET^DG RUGMFU is an example of this t ype of err or:
	13564	Figure 136 : F - Bloc k structur e mismatch —Sample co de error
	13565	ENGET() ;D ETERMINE D IVISION TO GET SUBSC RIBERS
	13566	;
	13567	N I,J,X
	13568	F I =1:1 X HLN EXT Q:HLQU IT’>0 D
	13569	.S X(I)=HLNOD E,J=0
	13570	..F S J=$O(H LNODE(J)) Q:’J S X( I,J)=HLNOD E(J)
	13571
	13572	Because th ere is no DO command before th e double d ot syntax, that line is never executed.
	13573	F - Call t o missing label ‘lab el’ in thi s routine
	13574	In this ca se, refere nce is mad e to a lab el inside a routine that is no t (or no l onger) pre sent. Ther e could be many reas ons for th is. The mo st likely candidate being remo val of cod e that is no longer used.
	13575	F - Call t o this lab el/routine (MISSING LABEL)
	13576	This is th e compleme ntary situ ation in w hich code calls a la bel/routin e that is no longer present on the syste m. Again, there are a number o f reasons why this m ight occur , includin g typograp hical erro rs and rem oval of co de that is no longer used.
	13577	F - Comman d missing an argumen t
	13578	This is an other synt ax type er ror. Most M command arguments are option al. This e rror is us ually asso ciated wit h the WRIT E argument tab chara cter, whic h is the q uestion ma rk (?). It must be f ollowed by an intege r or varia ble.
	13579	F - Error in pattern code
	13580	XINDEX che cks that o nly the se ven patter n codes (i .e., ACELN PU) are us ed. They a lso can be lower cas e (i.e., a celnpu).
	13581	F - FOR Co mmand foll owed by on ly one spa ce
	13582	This error is only f or the arg umentless FOR comman d. It must be follow ed by two spaces.
	13583	F - FOR Co mmand did not contai n ‘=‘
	13584	XINDEX che cks that i f the FOR command ha s an argum ent, it mu st set a v ariable.
	13585	F - Genera l Syntax E rror
	13586	This error indicates a constru ct that is not valid M syntax and is oth erwise unr ecognized. Almost an y malforme d code is possible h ere.
	13587	F - GO or DO mismatc h from blo ck structu re (M45)
	13588	This is an other erro r that has to with t he dot syn tax used t o create a nonymous b locks in s tandard M. Typically , a GOTO t hat jumps from one s tack level to anothe r would ge nerate thi s type of error.
	13589	Figure 137 : F - GO o r DO misma tch from b lock struc ture (M45) —Sample co de error
	13590
	13591	TEST ;test ro utine
	13592	F I=1:1 D
	13593	. S X=1, Y=Z
	13594	.I Y>0 G QUIT^TEST A
	13595	.S Z=0
	13596
	13597
	13598	In this ex ample, the code is t rying to G O out of t he DO bloc k to anoth er routine .
	13599	F - Invali d or wrong number of arguments to a func tion
	13600	This error involves calling fu nctions wi th the wro ng number of argumen ts, or wit h invalid argument s yntax.
	13601	F - Label is not val id
	13602	M allows t he argumen ts to comm ands (e.g. , DO) to b e specifie d indirect ly (i.e., via the “@ ” syntax). What is n ot standar d, however , is to us e indirect ion just t o specify the label in a label ^routine c ombination .
	13603	The follow ing code e xtract fro m EN+6^MXM LPRSE is i nvalid:
	13604	Figure 138 : F - Labe l is not v alid—Sampl e code err or
	13605	F Q:EOD D READ,EPO S,@ST^MXML PRS0:’EOD
	13606
	13607	F - Missin g argument to a comm and post-c onditional
	13608	Most M com mands allo w a post c ondition, which is d esignated by a colon and follo wed by the argument. This erro r occurs i f the argu ment is mi ssing.
	13609	F - Non-st andard (Un defined) ‘ Z’ command
	13610	XINDEX fla gs all use s of “Z” c ommands. V endor-spec ific comma nds use th e “Z” pref ix. The SA C restrict s the use of such co mmands to Kernel. Yo u may occa sionally s ee other p ackages ma ke use of these comm ands, but in these c ases, an e xemption i s required .
	13611	F - Quoted string no t followed by a sepa rator
	13612	XINDEX che cks that a nywhere a quoted str ing is use d, it must stand alo ne or have a separat or after i t.
	13613	F - Refere nce to rou tine ‘^rou tine name’ . That isn ’t in this UCI
	13614	These erro rs flag re ferences t o routines that are not presen t on the s ystem.
	13615	F - UNDEFI NED COMMAN D (rest of line not checked)
	13616	This is a syntax err or. It req uires a ma nual check of the li ne/routine .
	13617	F - Undefi ned Functi on
	13618	Checks tha t a functi on is part of the M standard.
	13619	F - Undefi ned Specia l Variable
	13620	This is es sentially the same a s the “F - Undefined Function” error. Th e only dif ference is that in M special v ariables a re built-i n function s that tak e no argum ents.
	13621	F - Unmatc hed Parent hesis
	13622	This is a syntax err or. XINDEX checks th at the sta tic code h as matchin g parenthe sis. It do es have pr oblems whe n indirect ion is use d, which a re evaluat ed during execution.
	13623	F - Unmatc hed Quotat ion Marks
	13624	This is a syntax err or. XINDEX checks th at the sta tic code h as matchin g quotatio n marks. I t does hav e problems when indi rection is used, whi ch are eva luated dur ing execut ion.
	13625	F - Unreco gnized arg ument in S ET command
	13626	XINDEX che cks the sy ntax of th e SET stat ement. It does have problems w hen indire ction is u sed, which are evalu ated durin g executio n.
	13627
	13628	Warning Vi olation Er rors (Acco rding to V A Conventi ons)
	13629	W - Blank( s) at end of line
	13630	Standard M has very specific w hitespace requiremen ts. Some t ext editor s create e xtra white space that is caught by XINDEX .
	13631	W - Duplic ate label, (M57)
	13632	This is an M standar d error. D uring exec ution, the first occ urrence of the label is execut ed.
	13633	W - First line label NOT routi ne name
	13634	The first line of Vi stA routin es is requ ired to be a label t hat is the same as t he routine name.
	13635	W - Invali d global v ariable na me
	13636	Checks tha t the glob al name is upper cas e and not longer tha n eight ch aracters.
	13637	W - Invali d local va riable nam e
	13638	XINDEX che cks that t he local v ariable na me is uppe r case and not longe r than six teen chara cters.
	13639	W - Line c ontains a CONTROL (n on-graphic ) characte r
	13640	The only n on-graphic character s permitte d in VistA routines are whites pace.
	13641	W - Null l ine (no co mmands or comment)
	13642	Every line in an M r outine mus t contain at least o ne charact er. The mo st common single cha racter is the semi-c olon (“;”) , which de notes a co mment.
	13643
	13644	Standards Violation Errors (Ac cording to VA Standa rds)
	13645	S - $View function u sed
	13646	The $VIEW function d irectly ex amines mem ory. The u se of $VIE W is restr icted to K ernel and VA FileMan .
	13647	S - Access to SSVN’s restricte d to Kerne l
	13648	Structured System Va riable Nam es (SSVNs) are a mec hanism use d to provi de program matic info rmation to certain s ystem info rmation an d are cove red in Sec tion 7.1.3 of the M language s tandard. T he use of SSVNs is r estricted to Kernel.
	13649	Common SSV Ns include the follo wing:
	13650	^$ROUTINE
	13651	^$JOB
	13652	^$LOCK
	13653	^$GLOBAL
	13654	S - Break command us ed
	13655	The BREAK command is prohibite d except f or Kernel.
	13656	If applica tions ever need to u se BREAK, they shoul d use ^%ZO SF(“BRK”) and ^%ZOSF (“NBRK”) i nstead.
	13657	S - Extend ed referen ce
	13658	In M, use extended r eferences to refer t o routines or global s outside the curren t environm ent (calle d a namesp ace in Cac hé). The u se of exte nded refer ences is r estricted to Kernel.
	13659	S - First line of ro utine viol ates the S AC
	13660	Section 2. 2.1 of the SAC speci fies the f ormat of t he first l ine of a r outine as follows:
	13661	2.2.1 The first line of a rout ine must b e in the f ollowing f ormat: rou tine name< ls>; site/ programmer <space>-<s pace>brief descripti on [option al space]; date [time is option al].
	13662	ZZAA12 ;DA LOI/XXX - Example Ro utine;2/13 /07
	13663	NOTE: M ed itors freq uently mod ify the fi rst line o f a routin e.
	13664	S - 2nd li ne of rout ine violat es the SAC
	13665	In VistA, the second line of r outines re cords the following informatio n:
	13666	Package/Ap plication version nu mber
	13667	Package/Ap plication name
	13668	Patches ID numbers ( if any app lied)
	13669	Original r outine cre ation date & time
	13670	Build numb er
	13671	Section 2. 2.2 of the SAC speci fies the s econd line format as follows:
	13672	2.2.2 The second lin e of a rou tine must be in the following format: [L ABEL-optio nal]<ls>;; version nu mber; pack age name; pm,...pn ; versio n date;Bui ld n where :
	13673	;;1.0;PACK AGE;pm,… pn;Feb 1 , 2007;Bui ld 1
	13674	S - Patch number ‘nn n’ missing from seco nd line
	13675	The list o f patch nu mbers must fall betw een the se t of aster isks (“**” ) and be s eparated b y commas a s shown in Section 2 .2.2 of th e SAC (see Section 2 6.13.3.3.6 ).
	13676	S - ‘HALT’ command s hould be i nvoked thr ough ‘G ^X USCLEAN’
	13677	The HALT c ommand cau ses a prog ram to exi t; this is not a com mon requir ement in V istA. If f or some re ason a rou tine needs to halt, you must f irst perfo rm certain housekeep ing tasks. Kernel pr ovides an API to cle anly halt a program. Applicati on program s cannot u se the HAL T command.
	13678	Anomaly
	13679	This repor ted error message is out of da te; applic ations sho uld use H^ XUS (see S ection 2.4 .3 of the SAC).
	13680	S - Kill o f a protec ted variab le (variab le name)
	13681	Kernel mak es use of certain lo cal variab les to mai ntain a st andard env ironment f or process es. Applic ations can not KILL t he followi ng variabl es:
	13682	DT
	13683	DTIME
	13684	DUZ
	13685	IOST
	13686	IOM
	13687	U
	13688	S - Kill o f an unsub scripted g lobal
	13689	The SAC sp ecifies th at unsubsc ripted glo bals shall be killed :
	13690	2.3.2.3 Th e KILLing of unsubsc ripted glo bals is pr ohibited a nd should be protect ed. (Speci al instruc tion to th e site is required t o enable t he killing of an uns ubscripted global. A pplication developer s must doc ument when calls to EN^DIU2 ar e made to delete fil es stored in unsubsc ripted glo bals).
	13691	S - Unargu mented Kil l
	13692	Kernel mai ntains a s et of loca l variable s that can not be SET or KILLed . The unar gumented K ILL is pro hibited ex cept for K ernel.
	13693	S - Exclus ive Kill
	13694	The use of the exclu sive KILL is prohibi ted except for Kerne l.
	13695	S - Exclus ive or Una rgumented NEW comman d
	13696	The exclus ive NEW co mmand is t he same as the exclu sive KILL and is res tricted ex cept for K ernel.
	13697	S - LABEL+ OFFSET syn tax
	13698	The only s ituation i n which ap plication routines a re allowed to use th e LABEL+OF FSET synta x to refer to lines of code is when usin g $TEXT to retrieve data lines . For exam ple, it ca nnot be us ed in conj unction wi th a DO or GOTO comm and.
	13699	S - Line i s longer t han 245 by tes
	13700	Lines of c ode cannot be longer than 245 bytes.
	13701	S - Lock m issing Tim eout
	13702	In M, a LO CK command may inclu de a timeo ut. If the specified timeout p eriod expi res before obtaining the lock, the LOCK command fa ils. In Vi stA, appli cation pro grams are required t o specify a timeout when using this comm and. If fo r some rea son it is necessary to use a L OCK with n o timeout (e.g., to manage col laborating processes ), an exem ption is r equired.
	13703	NOTE: Kern el can use locks wit hout a tim eout. Kern el can als o use non- incrementa l and unar gumented l ocks.
	13704	S - Lower/ Mixed case Variable name used
	13705	The rules regarding variable c ase have b een relaxe d somewhat in the mo st recent revision o f the SAC. The relev ant sectio ns are:
	13706	2.2.5 The line body must conta in at leas t 1 printa ble charac ter, must not exceed 245 chara cters in l ength, and must cont ain only t he ASCII c haracters values 32- 126. Line labels, gl obal varia ble names, system va riables, S SVNs, etc. must be u ppercase.
	13707
	13708	2.3.1.1 Lo cal variab le names m ay not exc eed sixtee n characte rs. Namesp aced varia bles may n ot contain lowercase character s. Variabl es local t o a routin e, subrout ine or DoD ot may be any case. Any variab le contain ing lowerc ase charac ters must be NEWed a t the begi nning of t he routine , subrouti ne or DoDo t.
	13709	S - Lowerc ase comman d(s) used in line
	13710	All M comm ands must be upper c ase. They can be spe lled out o r abbrevia ted to the first cha racter.
	13711	S - Non-In cremental Lock
	13712	M allows l ocks to be one of th e followin g types:
	13713	Incrementa l—Allows a process t o maintain multiple locks on t he same re source and release t hem one at a time.
	13714	Non-Increm ental—Eith er a proce ss obtains the lock or the com mand fails .
	13715	Applicatio n programs are requi red to use the incre mental for m of the L OCK comman d.
	13716	NOTE: This restricti on does no t apply to Kernel.
	13717	S - Non-st andard $Z function u sed
	13718	M implemen tations ma y provide special fu nctions wi th names b eginning w ith $Z. Th ese are pl atform dep endent. Ap plication programs c annot use them.
	13719	NOTE: This restricti on does no t apply to Kernel.
	13720	S - Non-st andard $Z special va riable use d
	13721	M implemen tations ma y provide special va riables wi th names b eginning w ith $Z. Th ese are pl atform dep endent. Ap plication programs c annot use them.
	13722	NOTE: This restricti on does no t apply to Kernel.
	13723	S - ‘OPEN’ command s hould be i nvoked thr ough ^%ZIS
	13724	Applicatio ns cannot directly u se the OPE N and CLOS E commands . Instead, they must use the K ernel Devi ce Handler .
	13725	NOTE: This restricti on does no t apply to Kernel, M ailMan, an d VA FileM an. See th e noted ex emptions i n Section 2.4.8.1 of the SAC.
	13726	Anomaly
	13727	This error is a bit misleading , because there are now severa l APIs oth er than ^% ZIS that c an be used . This inc ludes:
	13728	^%ZISH
	13729	^%ZISUTL
	13730	^%ZISTCP
	13731	Regardless , applicat ions must use one of the ^%ZIS * APIs and cannot us e OPEN dir ectly.
	13732	REF: For m ore detail s of the C LOSE comma nd, see th e “S - ‘Cl ose’ comma nd should be invoked through ‘ D ^%ZISC’” section.
	13733	S - ‘Close ’ command should be invoked th rough ‘D ^ %ZISC’
	13734	Kernel’s D evice Hand ler encaps ulates cer tain I/O-r elated com mands (e.g ., OPEN an d CLOSE) a nd provide s a common device ab straction used by Vi stA applic ations. Ap plications are requi red to use the Devic e Handler.
	13735	At one tim e, devices were alwa ys opened using D ^% ZIS and cl osed using D ^%ZISC, but that is no long er true. K ernel prov ides some additional APIs:
	13736	^%ZISH fo r working with host files (tha t is, oper ating syst em files).
	13737	^%ZISUTL t o make wor king with multiple d evices eas ier.
	13738	^%ZISTCP f or TCP con nections.
	13739	If a devic e is opene d using OP EN^%ZISUTL , it must be closed with CLOSE ^%ZISUTL. Do not clo se the dev ice throug h the CLOS E command.
	13740	S - Read c ommand doe sn’t have a timeout
	13741	Applicatio n programs must prov ide a time out (usual ly the var iable DTIM E) when us ing the RE AD command . In fact, it is goo d practice for appli cations to not use R EAD at all , but use the VA Fil eMan ^%DIR API (comm only known as the Re ader); tho ugh, this is not a r equirement . It is, h owever, a requiremen t to use a timeout.
	13742	In additio n, if a ti meout exce eds 300 se conds, you must docu ment that fact in th e package technical manual.
	13743	If for som e reason t his is ina ppropriate , an exemp tion is re quired.
	13744	S - Routin e code exc eeds SACC maximum si ze of 1500 0 (nnnnn)
	13745	The maximu m routine size for M code and “;;” comme nts (comme nts beginn ing with d ouble semi -colons ar e consider ed code) i s set to 1 5K charact ers in a r outine.
	13746	NOTE: An a dditional 5K charact ers in a r outine is available for regula r comments (i.e., co mments beg inning wit h a single semi-colo n).
	13747	S - Routin e exceeds SACC maxim um size of 20000 (nn nnn)
	13748	The maximu m routine size as de termined b y ^%ZOSF(“ SIZE”) is set to 20K for all c haracters in a routi ne.
	13749	S - Set to a ‘%’ glo bal
	13750	Applicatio n programs cannot mo dify globa ls with na mes beginn ing with “ %”.
	13751	NOTE: This restricti on does no t apply to Kernel.
	13752	S - Should use ‘TASK MAN’ inste ad of ‘JOB ’ command
	13753	This is a requiremen t. Applica tion progr ams cannot start bac kground pr ocesses wi th the JOB command, but must u se one of the APIs p rovided by TaskMan.
	13754	NOTE: This restricti on does no t apply to Kernel.
	13755	S - View c ommand use d
	13756	The VIEW c ommand mod ifies memo ry or disk buffers. Use of thi s command is restric ted to Ker nel and VA FileMan.
	13757	REF: For m ore detail s about VI EW and $VI EW, see th e “S - $Vi ew functio n used” se ction.
	13758	S - Violat es VA prog ramming st andards
	13759	This is so mething of a catchal l category and requi res manual review fo r violatio ns of VA p rogramming standards .
	13760	Informatio nal Errors
	13761	I - QUIT C ommand fol lowed by o nly one sp ace
	13762	This is an other whit espace iss ue. In sta ndard M, a routine i s terminat ed by a si ngle QUIT command an d a functi on returns a value w ith a QUIT followed by a singl e space an d then an expression that eval uates to t he value t o be retur ned. When you encoun ter a QUIT followed by a space , it is mo st likely extra whit espace at the end of a line.
	13763	I - Star o r pound RE AD used
	13764	In M, READ is normal ly a line- oriented c ommand. Ho wever, the re are two syntactic variation s on the R EAD comman d where it s use is i nappropria te:
	13765	Figure 139 : API - St ar our pou nd READ us ed—Syntact ic variati on (1 of 2 )
	13766	READ *X
	13767
	13768	Reads a si ngle chara cter into X.
	13769	Figure 140 : API - St ar our pou nd READ us ed—Syntact ic variati on (2 of 2 )
	13770	READ X#100
	13771
	13772	Reads 100 contiguous character s (bytes o n most M s ystems) in to X. Use of so-call ed star an d pound RE ADs was on ce disallo wed, but i s now perm itted so l ong as app lications follow oth er relevan t standard s.
	13773	Marked Ite ms Errors (Manual Ch eck)
	13774	You must m anually ch eck flagge d referenc es under M arked Item s.
	13775	Currently, Marked It ems only a pply if a line conta ins $TEXT ($T). XIND EX records the locat ion of the $T code a nd prints it out und er the “Ma rked Items ” sub-head er on the XINDEX rep ort, since XINDEX do es not che ck the ref erences of a $T.
	13776	M uses the $TEXT fun ction to r etrieve li nes from a routine, and routin es sometim es incorpo rate data items that are retri eved in th is fashion . Section 2.2.4 of t he SAC des cribes the required format for lines ref erenced by $TEXT, wh ich states (in part) :
	13777	2.2.4.1 LA BEL+OFFSET reference s are not used excep t for $TEX T referenc es.
	13778
	13779	2.2.4.2 Li nes refere nced by $T EXT for us e other th an to chec k for the existence of a routi ne or a li ne label i n that rou tine must be in the following format: [L ABEL-optio nal]<ls>;; text or M code.
	13780	In standar d M, a sem icolon (“; ”) introdu ces commen ts. A doub le semicol on (“;;”) indicates that the c omment sho uld be pre served eve n if the r outine is compiled. The LABEL+ OFFSET syn tax is req uired to p revent err ors that c ould be in troduced i f lines ar e inserted ahead of the label. According to the SA C, if code uses $T, the refere nce must s tart with a double s emicolon ( “;;”).
	13781
	13782
	13783	Unwinder: Developer Tools
	13784	Applicatio n Programm ing Interf ace (API)
	13785	Several AP Is are ava ilable for developer s to work with Kerne l Unwinder . These AP Is are des cribed bel ow.
	13786	EN^XQOR(): Navigatin g Protocol s
	13787	Reference Type:Suppo rted
	13788	Category:U nwinder
	13789	ICR #:1010 1
	13790	Descriptio n:This API is the ma in routine for navig ating prot ocols. The routine p rocesses t he initial protocol and the su bordinate protocols. This proc essing of subordinat e protocol s happens according to the typ e of proto col and th e navigati on variabl es that ge t set alon g the way.
	13791	Format:EN^ XQOR(x)
	13792	Input Para meters:x:( required) Identifies the initi al protoco l that EN^ XQOR shoul d process. The “x” i nput param eter shoul d be in va riable poi nter forma t. For exa mple:
	13793	x=“1234;OR D(101,”
	13794	This would cause the processin g to start with the protocol t hat has an internal entry numb er (IEN) o f 1234.
	13795	An alterna tive to us ing variab le pointer format is to set x equal to t he name or number of the proto col and DI C equal to the numbe r or globa l referenc e of the f ile you ar e working in (genera lly the PR OTOCOL fil e [#101]).
	13796	Output:non e.
	13797
	13798	EN1^XQOR() : Navigati ng Protoco ls
	13799	Reference Type:Suppo rted
	13800	Category:U nwinder
	13801	ICR #:1010 1
	13802	Descriptio n:This API is identi cal to the EN^XQOR() : Navigati ng Protoco ls API, ex cept that the entry and exit a ctions of the initia l protocol are not e xecuted. T his API pr ovides bac kwards com patibility with the way Kernel 6 process ed protoco ls that we re defined in the OP TION file (#19).
	13803	Format:EN1 ^XQOR(x)
	13804	Input Para meters:x:( required) Identifies the initi al protoco l that EN^ XQOR shoul d process. The “x” i nput param eter shoul d be in va riable poi nter forma t. For exa mple:
	13805	x=“1234;OR D(101,”
	13806	This would cause the processin g to start with the protocol t hat has an internal entry numb er (IEN) o f 1234.
	13807	An alterna tive to us ing variab le pointer format is to set x equal to t he name or number of the proto col and DI C equal to the numbe r or globa l referenc e of the f ile you ar e working in (genera lly the PR OTOCOL fil e [#101]).
	13808	Output:non e.
	13809
	13810	MSG^XQOR() : Enable H L7 Messagi ng
	13811	Reference Type:Suppo rted
	13812	Category:U nwinder
	13813	ICR #:1010 1
	13814	Descriptio n:This API enables H ealth Leve l Seven (H L7) messag ing throug h the XQOR Unwinder.
	13815	Format:MSG ^XQOR(prot ocol,.msgt ext)
	13816	Input Para meters:pro tocol:(req uired) The name of t he protoco l with whi ch the HL7 message a re associa ted.
	13817	.msgtext:( required) The array containing the HL7 m essage.
	13818	Output:non e.
	13819
	13820	EN^XQORM() : Menu Ite m Display and Select ion
	13821	Reference Type:Suppo rted
	13822	Category:U nwinder
	13823	ICR #:1014 0
	13824	Descriptio n:This API handles t he display of and se lection fr om a menu; this rout ine proces ses a sing le menu on ly. This i s the call that the EN^XQOR(): Navigatin g Protocol s API uses to obtain menu sele ctions. Th e caller i s responsi ble to han dle any se lections f rom the me nu that ar e returned in the y array. If you want n avigation to the sel ected item s handled for you, u se the EN^ XQOR(): Na vigating P rotocols A PI. The me nus handle d by this routine ar e the mult iple selec tion, mult iple colum n menus th at are typ ical in Or der Entry/ Results Re porting (O E/RR).
	13825	Format:EN^ XQORM(xqor m,xqorm(0) )
	13826	Input Para meters:xqo rm:(requir ed) A vari able point er to the menu that should be displayed (e.g., XQO RM=“1234;O RD(101,”).
	13827	xqorm(0):( required) A string o f flags th at control the displ ay and pro mpting of the menu:
	13828	Numeric—Ma ximum numb er of sele ctions all owed.
	13829	A—Prompt f or a selec tion from the menu.
	13830	D—Display the menu.
	13831	Output Par ameters:y( ):This arr ay contain s the item s that the user sele cted from the menu.
	13832
	13833	XREF^XQORM (): Force Menu Recom pile
	13834	Reference Type:Suppo rted
	13835	Category:U nwinder
	13836	ICR #:1014 0
	13837	Descriptio n:This API forces a menu to re compile. M enus are c ompiled in to the XUT L global. This shoul d happen a utomatical ly. Howeve r, you can use this API to for ce a menu to recompi le.
	13838	Format:XRE F^XQORM(xq orm)
	13839	Input Para meters:xqo rm:(requir ed) Variab le pointer to the pr otocol tha t should b e recompil ed.
	13840	Output:ret urns:Retur ns recompi led menu.
	13841
	13842	DISP^XQORM 1(): Displ ay Menu Se lections F rom Help C ode
	13843	Reference Type:Suppo rted
	13844	Category:U nwinder
	13845	ICR #:1010 2
	13846	Descriptio n:This API displays menu selec tions from help code , if you h ave replac ed the sta ndard help by settin g XQORM(“? ?”). This API should only be c alled from within th e code use d by XQORM (“??”).
	13847	Format:DIS P^XQORM1(x )
	13848	Input Para meters:x:( required) Must be “? ”.
	13849	Output:ret urns:Retur ns menu se lections.
	13850
	13851
	13852	User: Deve loper Tool s
	13853	Applicatio n Programm ing Interf ace (API)
	13854	Several AP Is are ava ilable for developer s to work with the u ser. These APIs are described below.
	13855	$$CODE2TXT ^XUA4A72() : Get HCFA Text
	13856	Reference Type:Suppo rted
	13857	Category:U ser
	13858	ICR #:1625
	13859	Descriptio n:This ext rinsic fun ction retu rns the th ree parts of the Hea lth Care F inancing A dministrat ion (HCFA) text from the PERSO N CLASS fi le (#8932. 1) based o n passing in the Int ernal Entr y Number ( IEN) or th e VA’s Vco de.
	13860	Format:$$C ODE2RXT^XU A4A72(ien_ or_vcode)
	13861	Input Para meters:ien _or_vcode: (required) Pass in e ither the Internal E ntry Numbe r (IEN) or the VA Vc ode for th e text tha t should b e returned .
	13862	Output:ret urns:Retur ns HCFA te xt.
	13863
	13864	$$GET^XUA4 A72(): Get Specialty and Subsp ecialty fo r a User
	13865	Reference Type:Suppo rted
	13866	Category:U ser
	13867	ICR #:1625
	13868	Descriptio n:This ext rinsic fun ction retu rns the “I EN^Profess ion^Specia lty^Sub-sp ecialty^Ef fect date^ Expired da te^VA code ” for the person ide ntified by the DUZ i n effect o n the date passed in , in inter nal VA Fil eMan forma t (TODAY i f no date passed in) .
	13869	NOTE: This API was e xported wi th Kernel patch XU8 .027.
	13870	It returns :
	13871	-1—If DUZ does not p oint to a valid user or user h as never h ad a Perso n Class as signed.
	13872	-2—If no a ctive Pers on Class o n that dat e.
	13873	Format:$$G ET^XUA4A72 (duz[,date ])
	13874	Input Para meters:duz :(required ) Internal Entry Num ber (IEN) for the pe rson being checked i n the NEW PERSON fil e (#200).
	13875	date:(opti onal) Date in intern al VA File Man format , to indic ate effect ive date f or determi nation.
	13876	Output:ret urns:Retur ns:
	13877	-1—If DUZ does not p oint to a valid user or user h as never h ad a Perso n Class as signed.
	13878	-2—If no a ctive Pers on Class o n that dat e.
	13879
	13880	$$IEN2CODE ^XUA4A72() : Get VA C ode
	13881	Reference Type:Suppo rted
	13882	Category:U ser
	13883	ICR #:1625
	13884	Descriptio n:This ext rinsic fun ction retu rns the VA CODE from the PERSO N CLASS fi le (#8932. 1) that co rresponds to the Int ernal Entr y Number ( IEN) passe d in. If t he IEN pas sed in doe s not matc h a valid entry in t he PERSON CLASS file (#8932.1) , an empty string is returned.
	13885	NOTE: Thi s API was exported w ith Kernel patch XU* 8.0*27.
	13886
	13887	Format:$$I EN2CODE^XU A4A72(ien)
	13888	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) in the PER SON CLASS file (#893 2.1).
	13889	Output:ret urns:Retur ns the VA CODE.
	13890
	13891	$$DTIME^XU P(): Reset DTIME for USER
	13892	Reference Type:Suppo rted
	13893	Category:U ser
	13894	ICR #:4409
	13895	Descriptio n:This ext rinsic fun ction rese ts the DTI ME variabl e for the user ident ified by t he first p arameter “ DUZ” of th is functio n. This ex trinsic fu nction acc epts two p arameters:
	13896	IEN or DUZ of the us er in the NEW PERSON file (#20 0).
	13897	IEN of the device in the DEVIC E file (#3 .5).
	13898	The return value sho uld be ass igned to t he variabl e DTIME as shown in the exampl es. This D TIME varia ble is use d on all t imed READS where int eractive r esponses a re require d for a gi ven user.
	13899	Format:$$D TIME^XUP([ duz][,ios] )
	13900	Input Para meters:duz :(optional ) The Inte rnal Entry Number (I EN) or DUZ of the us er in the NEW PERSON file (#20 0).
	13901	ios:(optio nal) The I EN of the device in the DEVICE file (#3. 5). This I EN should be the sam e value of IOS if pr esent, and should re flect the current si gn-on devi ce of the user.
	13902	Output:ret urns:The r eturn valu e is based on the fi rst availa ble data f ound in th e followin g fields/f iles (list ed in sear ch order):
	13903	TIMED READ (# OF SEC ONDS) fiel d (#200.1) of the NE W PERSON f ile (#200) .
	13904	TIMED READ (# OF SEC ONDS) fiel d (#51.1) of the DEV ICE file ( #3.5).
	13905	DEFAULT TI MED READ ( SECONDS) f ield (#210 ) of the K ERNEL SYST EM PARAMET ERS file ( #8989.3).
	13906	(default) If no data is availa ble in any of the th ree fields above, th en the ret urn value defaults t o 300 seco nds.
	13907
	13908	Examples
	13909	Example 1
	13910	Sending DU Z only, re turns the value in F ield #200. 1, TIMED R EAD (# OF SECONDS), of the NEW PERSON fi le (#200):
	13911	>S DTIME=$ $DTIME^XUP (DUZ)
	13912
	13913	>W DTIME
	13914	1800
	13915
	13916	Example 2
	13917	Sending DU Z and IOS, returns t he value i n Field #2 00.1, TIME D READ (# OF SECONDS ), of the NEW PERSON file (#20 0):
	13918	>S DTIME=$ $DTIME^XUP (DUZ,IOS)
	13919
	13920	>W DTIME
	13921	1800
	13922
	13923	Example 3
	13924	Sending IO S only, re turns the value in F ield #51.1 , TIMED RE AD (# OF S ECONDS), o f the DEVI CE file (# 3.5):
	13925	>S DTIME=$ $DTIME^XUP (,IOS)
	13926
	13927	>W DTIME
	13928	500
	13929
	13930	Example 4
	13931	Not Sendin g DUZ or I OS, return s the valu e in Field #210, DEF AULT TIMED READ (SEC ONDS), of the KERNEL SYSTEM PA RAMETERS f ile (#8989 .3):
	13932	>S DTIME=$ $DTIME^XUP (,)
	13933
	13934	>W DTIME
	13935	400
	13936	Or:
	13937	>S DTIME=$ $DTIME^XUP ()
	13938
	13939	>W DTIME
	13940	400
	13941
	13942	Example 5
	13943	Not Sendin g DUZ or I OS and no value is i n Field #2 10, DEFAUL T TIMED RE AD (SECOND S), of the KERNEL SY STEM PARAM ETERS file (#8989.3) :
	13944	>S DTIME=$ $DTIME^XUP ()
	13945
	13946	>W DTIME
	13947	300
	13948
	13949	$$ACTIVE^X USER(): St atus Indic ator
	13950	Reference Type:Suppo rted
	13951	Category:U ser
	13952	ICR #:2343
	13953	Descriptio n:This ext rinsic fun ction retu rns the ac tive statu s indicato r and late st signon informatio n of a use r in the N EW PERSON file (#200 ).
	13954	Format:$$A CTIVE^XUSE R(ien)
	13955	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the use r to be ch ecked in t he NEW PER SON file ( #200).
	13956	Output:ret urns:Retur ns any of the follow ing codes:
	13957	“”—Null, n o user rec ord found.
	13958	0—User can not sign o n.
	13959	0^DISUSER— User canno t sign on because of DISUSER f lag.
	13960	0^TERMINAT ED^FMDATE— User termi nated on d ate indica ted.
	13961	1^NEW—A ne w user, ca n sign on.
	13962	1^ACTIVE^F MDATE—An a ctive user , last sig non date.
	13963
	13964	Examples
	13965	Example 1
	13966	This is an example o f an Activ e User in the NEW PE RSON file (#200):
	13967	>S X=$$ACT IVE^XUSER( 1529)
	13968
	13969	>WRITE X
	13970	1^ACTIVE^3 030321.093 756
	13971
	13972	Example 2
	13973	This is an example o f a Termin ated User in the NEW PERSON fi le (#200):
	13974	>S X=$$ACT IVE^XUSER( 957)
	13975
	13976	>WRITE X
	13977	0^TERMINAT ED^2980504
	13978
	13979	Example 3
	13980	This is an example o f a User w ith no rec ord in the NEW PERSO N file (#2 00), retur ns a null string:
	13981	>S X=$$ACT IVE^XUSER( 999999999)
	13982
	13983	>W X
	13984
	13985	>
	13986
	13987	Example 4
	13988	This is an example o f a User i n the NEW PERSON fil e (#200) w ith the DI SUSER flag set:
	13989	>S X=$$ACT IVE^XUSER( 111)
	13990
	13991	>W X
	13992	0^DISUSER
	13993
	13994	$$DEA^XUSE R()—Get Us er’s DEA N umber
	13995	Reference Type:Suppo rted
	13996	Category:U ser: DEA e PCS Utilit y
	13997	ICR #:2343
	13998	Descriptio n:This ext rinsic fun ction retu rns a user ’s DEA num ber, if it exists in the DEA# field (#53 .2) in the NEW PERSO N file (#2 00). If th e DEA# fie ld value i s null, th e value re turned dep ends on th e optional flag inpu t paramete r.
	13999	NOTE: Fee Basis and C&A provid ers only r eturn DEA# or null.
	14000	NOTE: This API was o riginally requested as part of the Publi c Key Infr astructure (PKI) Pro ject. This API was u pdated wit h Kernel p atch XU8. 0580, whi ch was cre ated in su pport of t he Drug En forcement Agency (DE A) e-Presc ribing of Controlled Substance s (ePCS) U tility. Th is utility uses Publ ic Key Inf rastructur e (PKI) an d meets th e requirem ents propo sed by the DEA Inter im Final R ule (IFR) for Electr onic Presc riptions f or Control led Substa nces effec tive as of June 1, 2 010.
	14001	Format:$$D EA^XUSER([ flag],ien)
	14002	Input Para meters:fla g:(optiona l) This fl ag control s what is returned w hen the us er does no t have a v alue in th e DEA# fie ld (#53.2) of the NE W PERSON f ile (#200) .
	14003	FLAG is nu ll or “0”— This routi ne checks to see if the user h as values in the VA# field (#5 3.3) of th e NEW PERS ON file (# 200) and t he (new) F ACILITY DE A NUMBER f ield (#52) of the IN STITUTION file (#4). If values are found in both o f those fi elds, this routine r eturns the following :
	14004	FACILITY D EA NUMBER field (#52 )_”-”_VA# field(#53. 3)
	14005	FLAG is “1 ”—This rou tine check s to see i f the user has a val ue in the VA# field (#53.3) of the NEW P ERSON file (#200). I f a value is found i n that fie ld, this r outine ret urns that field valu e. Otherwi se, this r outine ret urns an em pty string .
	14006	ien:This i s the NEW PERSON fil e (#200) I EN for the entry to be checked .
	14007	Output:ret urns:Retur ns the DEA #: DEA# fi eld (#53.2 ) value or the value returned based on t he (option al) flag i nput param eter.
	14008
	14009	Examples
	14010	Example 1
	14011	The follow ing are th e data val ues for th is example :
	14012	DEA# (#53. 2) field = “AB123456 7”.
	14013	FACILITY D EA NUMBER field (#52 ) = “VA765 4321”.
	14014	VA# field (#53.3) = “789”.
	14015	If the FLA G input pa rameter is NULL or “ 0”, this A PI would r eturn “AB1 234567”.
	14016	If the FLA G input pa rameter is “1”, this API would return “A B1234567”.
	14017	Example 2
	14018	The follow ing are th e data val ues for th is example :
	14019	DEA# field (#53.2) = NULL.
	14020	FACILITY D EA NUMBER field (#52 ) = “VA765 4321”.
	14021	VA# field (#53.3) = “789”.
	14022	If the FLA G input pa rameter is NULL or “ 0”, this A PI would r eturn “VA7 654321-789 ”.
	14023	If the FLA G input pa rameter is “1”, this API would return “7 89”.
	14024	Example 3
	14025	The follow ing are th e data val ues for th is example :
	14026	DEA# (#53. 2) field = NULL.
	14027	FACILITY D EA NUMBER field (#52 ) = “VA765 4321”.
	14028	VA# field (#53.3) = NULL.
	14029	If the FLA G input pa rameter is NULL or “ 0”, this A PI would r eturn “” ( an empty s tring).
	14030	If the FLA G input pa rameter is “1”, this API would return “” (an empty string).
	14031	In both ca ses, it re turns an e mpty strin g.
	14032	Example 4
	14033	The follow ing are th e data val ues for th is example :
	14034	DEA# (#53. 2) field = NULL.
	14035	FACILITY D EA NUMBER field (#52 ) = “VA765 4321”.
	14036	VA# field (#53.3) = “789”.
	14037	PROVIDER T YPE field (#53.6) = “FEE BASIS ” or “C&A” .
	14038	If the FLA G input pa rameter is NULL or “ 0”, this A PI would r eturn “” ( an empty s tring).
	14039	If the FLA G input pa rameter is “1”, this API would return “” (an empty string).
	14040	In both ca ses, it re turns an e mpty strin g.
	14041	$$DETOX^XU SER()—Get Detox/Main tenance ID Number
	14042	Reference Type:Suppo rted
	14043	Category:U ser: DEA e PCS Utilit y
	14044	ICR #:2343
	14045	Descriptio n:This ext rinsic fun ction obta ins the va lue stored in the DE TOX/MAINTE NANCE ID N UMBER fiel d (#53.11) in the NE W PERSON f ile (#200) . It retur ns one of the follow ing:
	14046	User’s DET OX/MAINTEN ANCE ID nu mber—If it exists in the DETOX /MAINTENAN CE ID NUMB ER field ( #53.11) of the NEW P ERSON file (#200).
	14047	Null—If DE TOX/MAINTE NANCE ID n umber is n ull or the DEA EXPER ATION DATE field (#7 47.44) in the NEW PE RSON file (#200) is unpopulate d.
	14048	DEA EXPIRA TION DATE (#747.44)— This date is returne d when the DETOX/MAI NTENANCE I D number i s valid bu t the DEA EXPIRATION DATE has expired.
	14049	NOTE: This API was r eleased wi th Kernel patch XU8 .0580, wh ich was cr eated in s upport of the Drug E nforcement Agency (D EA) e-Pres cribing of Controlle d Substanc es (ePCS) Utility. T his utilit y uses Pub lic Key In frastructu re (PKI) a nd meets t he require ments prop osed by th e DEA Inte rim Final Rule (IFR) for Elect ronic Pres criptions for Contro lled Subst ances effe ctive as o f June 1, 2010.
	14050	Format:$ $ DETOX^XUSE R(ien)
	14051	Input Para meters:ien :(required ) The IEN of the use r in NEW P ERSON file (#200).
	14052	Output:ret urns:Retur ns: one of the follo wing:
	14053	User’s DET OX/MAINTEN ANCE ID nu mber—If va lid.
	14054	Null—DETOX /MAINTENAN CE ID numb er is null or the DE A EXPERATI ON DATE fi eld (#747. 44) in the NEW PERSO N file (#2 00) is unp opulated.
	14055	DEA EXPIRA TION DATE (#747.44)— When the DETOX/MAIN TENANCE ID number is valid but the DEA E XPIRATION DATE has e xpired.
	14056
	14057	DIV4^XUSE R(): Get U ser Divisi ons
	14058	Reference Type:Contr olled Subs cription
	14059	Category:U ser
	14060	ICR #:2533
	14061	Descriptio n:This API returns a ll divisio ns for a u ser. It re turns:
	14062	1—If the u ser has a Division e ntry in th e NEW PERS ON file (# 200). It i ndicates t hat the ar ray of poi nters to t he Institu tion file has been d efined.
	14063	0—The arra y of point ers to the INSTITUTI ON file (# 4) has not been defi ned.
	14064	Format:DIV 4^XUSER(.a rray[,duz] )
	14065	Input Para meters:.ar ray:(requi red) This parameter is a local variable (i.e., arr ay name) p assed by r eference.
	14066	duz:(optio nal) The I nternal En try Number (IEN) of the user i n the NEW PERSON fil e (#200). If DUZ is not passed as a para meter, the function defaults t o the valu e of DUZ i n the appl ication’s partition.
	14067	Output Par ameters:.a rray:Retur ns:
	14068	1—If the u ser has a Division e ntry in th e NEW PERS ON file (# 200). It i ndicates t hat the ar ray of poi nters to t he Institu tion file has been d efined.The array inc ludes all IENs for t he INSTITU TION file (#4) that have been assigned t o the user .The array is define d and left in the ap plication’ s partitio n, if the user indic ated by th e value of the DUZ i nput param eter has d ivisions d efined in the respec tive NEW P ERSON file (#200) en try. The f ormat is:
	14069	ARRAY([^DI C(4 IEN])
	14070	0—The arra y of point ers to the INSTITUTI ON file (# 4) has not been defi ned.
	14071
	14072	Example
	14073	>S X=$$DIV 4^XUSER(.Z Z,duz)
	14074
	14075	$$LOOKUP^X USER(): Ne w Person F ile Lookup
	14076	Reference Type:Suppo rted
	14077	Category:U ser
	14078	ICR #:2343
	14079	Descriptio n:This ext rinsic fun ction does a user lo okup on th e NEW PERS ON file (# 200) scree ning out u sers that are termin ated. You are first asked to e nter a nam e of a use r in the N EW PERSON file (#200 ). By defa ult, the f unction th en asks if the corre ct user na me was sel ected. For example:
	14080	Select NEW PERSON NA ME: XUUSER ,THREE
	14081	Is XUUSER, THREE the one you wa nt? YES//
	14082	If the opt ional inpu t paramete r is set t o “Q” then the secon d, confirm ation prom pt is supp ressed. Th e return i s in the s ame format as a call to DIC (i .e., IEN^N AME). Addi ng new ent ries is no t allowed.
	14083	Format:$$L OOKUP^XUSE R([“”])
	14084	Input Para meters:“”: (optional) This opti onal input parameter does the following:
	14085	Null (defa ult)—Do no t suppress the NEW P ERSON file (#200) na me confirm ation prom pt for eac h entry se lected.
	14086	A—Screen o ut termina ted users.
	14087	Q—Suppress the NEW P ERSON file (#200) na me confirm ation prom pt for eac h entry se lected.
	14088	AQ—Screen out termin ated users and suppr ess the NE W PERSON f ile (#200) name conf irmation p rompt for each entry selected.
	14089	Output:ret urns:Retur ns the Int ernal Entr y Number ( IEN) and N AME of the user in t he NEW PER SON file ( #200) ente red after the “Selec t NEW PERS ON NAME:” prompt (IE N^NAME).
	14090
	14091	Examples
	14092	Example 1
	14093	This is an example o f a lookup of an act ive user w hen not pa ssing in t he optiona l “Q” para meter:
	14094	Figure 141 : $$LOOKUP ^XUSER API —Example 1 : Showing confirmati on prompt
	14095	>S LRDOC=$ $LOOKUP^XU SER(“”)
	14096
	14097	Select NEW PERSON NA ME: ?
	14098	Answer wi th NEW PER SON NAME, or INITIAL , or SSN, or VERIFY CODE, or
	14099	NICK NAME , or SERVI CE/SECTION , or DEA#, or ALIAS
	14100	Do you wa nt the ent ire 1601-E ntry NEW P ERSON List ? N <Enter > (No)
	14101	Select NEW PERSON NA ME: XUUSER ,TWO E <En ter> TX COMPUTER SPECIALIS T
	14102	Is XUUSER, TWO E the one you wa nt? YES// <Enter>
	14103
	14104	>W LRDOC
	14105	1529^XUUSE R,TWO E
	14106
	14107	Example 2
	14108	This is an example o f a lookup of an act ive user w hen passin g in the o ptional “Q ” paramete r:
	14109	Figure 142 : $$LOOKUP ^XUSER API —Example 2 : Suppress ing confir mation pro mpt
	14110	>S LRDOC=$ $LOOKUP^XU SER(“Q”)
	14111
	14112	Select NEW PERSON NA ME: XUUSER ,TWO E <En ter> TX COMPUTER SPECIALIS T
	14113
	14114	>W LRDOC
	14115	1529^XUUSE R,TWO E
	14116
	14117	Example 3
	14118	This is an example o f a lookup of a term inated use r when pas sing in th e optional “A” param eter:
	14119	Figure 143 : $$LOOKUP ^XUSER API —Example 3 : Terminat ed user
	14120	>S LRDOC=$ $LOOKUP^XU SER(“A”)
	14121
	14122	Select NEW PERSON NA ME: XUUSER ,EIGHT <En ter> EX
	14123	Thi s user was terminate d on May 0 4, 1998
	14124	Select NEW PERSON NA ME:
	14125
	14126	$$NAME^XUS ER(): Get Name of Us er
	14127	Reference Type:Suppo rted
	14128	Category:U ser
	14129	ICR #:2343
	14130	Descriptio n:This ext rinsic fun ction retu rns the fu ll name of the speci fied user in a mixed case disp layable fo rmat. The user’s giv en name (i .e., First Last) is returned u nless a se cond param eter of “F ” is passe d in to ge t the Fami ly name (i .e., Last, First).
	14131	Format:$$N AME^XUSER( ien[,forma t])
	14132	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the pro vider to b e checked in the NEW PERSON fi le (#200).
	14133	format:(op tional) Th is paramet er indicat es if the user’s nam e should b e returned formatted by Family or Given name, resp ectively. Possible v alues are:
	14134	F—Family ( e.g., “Xuu ser,Two”).
	14135	G (default )—Given (e .g., “Two Xuuser”).
	14136	Output:ret urns:Retur ns user’s family or given name .
	14137
	14138	Examples
	14139	Example 1
	14140	Retrieving the user name in Gi ven format :
	14141	>S X=$$NAM E^XUSER(15 29)
	14142
	14143	>W X
	14144	Two E Xuus er
	14145
	14146	Example 2
	14147	Retrieving the user name in Fa mily forma t:
	14148	>S X=$$NAM E^XUSER(15 29,“F”)
	14149
	14150	>W X
	14151	Xuuser,Two E.
	14152
	14153	$$PROVIDER ^XUSER(): Providers in New Per son File
	14154	Reference Type:Suppo rted
	14155	Category:U ser
	14156	ICR #:2343
	14157	Descriptio n:This ext rinsic fun ction was requested to be adde d by the C omputerize d Patient Record Sys tem (CPRS) Developme nt Team. I t indicate s any prov ider in th e NEW PERS ON file (# 200). The definition of a prov ider is an y entry in the NEW P ERSON file (#200) th at does no t have a t ermination date. Add itional pa rameters m ay be adde d in the f uture in o rder to pe rform othe r tests/ch ecks.
	14158	Format:$$P ROVIDER^XU SER(ien)
	14159	Input Para meters:ien :(required ) Internal Entry Num ber (IEN) of the pro vider to b e checked in the NEW PERSON fi le (#200).
	14160	Output:ret urns:Retur ns any of the follow ing codes:
	14161	1—Provider has a rec ord and no terminati on date.
	14162	0^TERMINAT ED^FMDATE— Provider t erminated on date in dicated.
	14163	“”—Null, n o provider record fo und.
	14164
	14165	Examples
	14166	Example 1
	14167	This is an example o f an Activ e Provider in the NE W PERSON f ile (#200) :
	14168	>S X=$$PRO VIDER^XUSE R(1529)
	14169
	14170	>WRITE X
	14171	1
	14172
	14173	Example 2
	14174	This is an example o f a Termin ated Provi der in the NEW PERSO N file (#2 00):
	14175	>S X=$$PRO VIDER^XUSE R(957)
	14176
	14177	>W X
	14178	0^TERMINAT ED^2980504
	14179
	14180	Example 3
	14181	This is an example o f a Provid er with no record in the NEW P ERSON file (#200), r eturns a n ull string :
	14182	>S X=$$PRO VIDER^XUSE R(00099999 9)
	14183
	14184	>W X
	14185
	14186	>
	14187
	14188	$$SDEA^XUS ER()—Check for Presc ribing Pri vileges
	14189	Reference Type:Suppo rted
	14190	Category:U ser: DEA e PCS Utilit y
	14191	ICR #:2343
	14192	Descriptio n:This ext rinsic fun ction uses the follo wing “Priv ileges Alg orithm” to check for prescribi ng privile ges:
	14193	Blank = ne ver answer ed (Allow all schedu les but sy stem to se nd the fol lowing ele ctronic me ssage: “DE A credenti als have n ot been po pulated, c all TBD re sponsible person.”)
	14194	Any or all fields ar e answered = provide explicit set of per missions ( that have been ident ified).
	14195	If it is a nswered th at Prescri ber has No privilege s for all schedules = remove D EA number or VA numb er from th e NEW PERS ON file (# 200).
	14196	If Prescri ber has be en issued a DEA numb er, you ha ve privile ges.
	14197	If the Pre scriber ha s been iss ued a VA n umber, thi s is a pre sumption o f privileg es.
	14198	NOTE: Not all of th ese checks apply to documentat ion of non -VA medica tion.
	14199	REF: This API calls the $$DEA ^XUSER()—G et User’s DEA Number API.
	14200	NOTE: Thi s API was released w ith Kernel patch XU* 8.0*580, w hich was c reated in support of the Drug Enforcemen t Agency ( DEA) e-Pre scribing o f Controll ed Substan ces (ePCS) Utility. This utili ty uses Pu blic Key I nfrastruct ure (PKI) and meets the requir ements pro posed by t he DEA Int erim Final Rule (IFR ) for Elec tronic Pre scriptions for Contr olled Subs tances eff ective as of June 1, 2010.
	14201	Format:$$S DEA^XUSER( [fg,]ien,p sdea)
	14202
	14203	Input Para meters:fg: (optional) This flag is used f or $$DEA c all, see t he flag in put parame ter in the $$DEA^XUS ER()—Get U ser’s DEA Number API .
	14204	ien:(requi red) This is the NEW PERSON fi le (#200) IEN for th e entry to be checke d.
	14205	psdea:(req uired) Thi s paramete r is DEA s chedule. D EA schedul e is a 2-6 position field. It comes from the DRUG file (#50) in Pharma cy. This A PI uses th is field t o verify t he provide r is allow ed to writ e orders f or specifi c controll ed substan ces. For e xample, if the sched ule is 2A, this indi cates a co ntrolled s ubstance, schedule 2 .
	14206	Chart for all values :
	14207	MANUFACTUR ED IN PHAR MACY
	14208	SCHEDULE 1 ITEM
	14209	SCHEDULE 2 ITEM
	14210	SCHEDULE 3 ITEM
	14211	SCHEDULE 4 ITEM
	14212	SCHEDULE 5 ITEM
	14213	LEGEND ITE M:
	14214	9—OVER-THE -COUNTER
	14215	L—DEPRESSA NTS AND ST IMULANTS
	14216	A—NARCOTIC S AND ALCO HOLS
	14217	P—DATED DR UGS
	14218	I—INVESTIG ATIONAL DR UGS
	14219	M—BULK COM POUND ITEM S
	14220	C—CONTROLL ED SUBSTAN CES - NON NARCOTIC
	14221	R—RESTRICT ED ITEMS
	14222	S—SUPPLY I TEMS
	14223	B—ALLOW RE FILL (SCH. 3, 4, 5 O NLY)
	14224	W—NOT RENE WABLE
	14225	F—NON REFI LLABLE
	14226	E—ELECTRON ICALLY BIL LABLE
	14227	N—NUTRITIO NAL SUPPLE MENT
	14228	U—SENSITIV E DRUG
	14229	Output:ret urns:Retur ns: DEA# o r Facility DEA_”-”_u ser VA# si milar to t he $$DEA c all.
	14230	1—DEA# is null from the $$DEA call.
	14231	2—When all schedules equals “0 ”.
	14232	4^expirati on date—DE A# expirat ion date h as expired . It check s if the D EA# and ex piration d ate are no t null. Th e expirati on date is returned in externa l format.
	14233
	14234	$$VDEA^XUS ER()—Check if User C an Sign Co ntrolled S ubstance O rders
	14235	Reference Type:Suppo rted
	14236	Category:U ser: DEA e PCS Utilit y
	14237	ICR #:2343
	14238	Descriptio n:This ext rinsic fun ction dete rmines if a user in the NEW PE RSON file (#200) is able to si gn orders for contro lled subst ances.
	14239	NOTE: This API was r eleased wi th Kernel patch XU8 .0580, wh ich was cr eated in s upport of the Drug E nforcement Agency (D EA) e-Pres cribing of Controlle d Substanc es (ePCS) Utility. T his utilit y uses Pub lic Key In frastructu re (PKI) a nd meets t he require ments prop osed by th e DEA Inte rim Final Rule (IFR) for Elect ronic Pres criptions for Contro lled Subst ances effe ctive as o f June 1, 2010.
	14240	Format:$VD EA^XUSER(. return,ien )
	14241	Input Para meters:.re turn:(requ ired) This is a refe rence to a n array wh ere the re asons why the user c annot sign orders fo r controll ed substan ces and wh ich DEA sc hedules th e user can prescribe is return ed. For ex ample:
	14242	RETURN(“Is permitted to prescr ibe all sc hedules.)= “”
	14243	ien:(requi red) This is the IEN of the us er in the NEW PERSON file (#20 0).
	14244	Output Par ameters:.r eturn:This array con tains the reasons wh y the user cannot si gn orders for contro lled subst ances and which DEA schedules the user c an prescri be. For ex ample:
	14245	RETURN(“Is not permi tted to pr escribe an y schedule s.”)=“”
	14246	Output:ret urns:Retur ns:
	14247	1—If the u ser is abl e to sign orders for controlle d substanc es.
	14248	0—If the u ser is not able to s ign orders for contr olled subs tances.
	14249
	14250	$$KCHK^XUS RB(): Chec k If User Holds Secu rity Key
	14251	Reference Type:Contr olled Subs cription
	14252	Category:U ser
	14253	ICR #:2120
	14254	Descriptio n:This ext rinsic fun ction chec ks to see if a user holds a gi ven securi ty key.
	14255	Format:$$K CHK^XUSRB( key[,ien])
	14256	Input Para meters:key :(required ) The name of the se curity key to be che cked.
	14257	ien:(optio nal) Inter nal Entry Number (IE N). It def aults to D UZ.
	14258	Output:ret urns:Retur ns:
	14259	1—User hol ds securit y key.
	14260	0—User doe s not hold security key.
	14261
	14262	Examples
	14263	Example 1
	14264	The follow ing exampl e illustra tes the re sults when a user ho lds a secu rity key i nput:
	14265	>S X=$$KCH K^XUSRB(“X UPROGMODE” )
	14266
	14267	>W X
	14268	1
	14269
	14270	Example 2
	14271	The follow ing exampl e illustra tes the re sults when a user do es not hol d the secu rity key i nput:
	14272	>S X=$$KCH K^XUSRB(“X UMGR”)
	14273
	14274	>W X
	14275	0
	14276
	14277	Example 3
	14278	The follow ing exampl e illustra tes the re sults when checking if another user hold s a securi ty key inp ut by incl uding thei r IEN:
	14279	>S X=$$KCH K^XUSRB(“X UPROGMODE” ,30)
	14280
	14281	>W X
	14282	1
	14283
	14284	DIVGET^XUS RB2(): Get Divisions for Curre nt User
	14285	Reference Type:Contr olled Subs cription
	14286	Category:U ser
	14287	ICR #:4055
	14288	Descriptio n:This API retrieves the list of divisio ns for the current u ser.(This was develo ped as a B roker Remo te Procedu re Call [R PC] and al l RPCs hav e as the f irst param eter the r eturn/outp ut paramet er.)
	14289	Format:DIV GET^XUSRB2 (ret,ien)
	14290	Input Para meters:ret :(required ) Name of the subscr ipted retu rn array. In every A PI that is used as a n RPC, the first par ameter is the return array.
	14291	ien:(requi red) The D UZ or user name of t he user fo r whom you are getti ng the div ision list .
	14292	Output Par ameters:re t():Return s a subscr ipted outp ut array. If + of th e value at the first level 0 s ubscript o f the retu rn value i s false, t hen the us er does no t have any divisions from whic h to selec t.
	14293	Otherwise, for each division t hat a user has, a no de is pres ent in the return va lue, at th e first su bscript le vel, start ing at zer o (0) and incrementi ng from th ere. The v alue of th e node is three piec es:
	14294	ien^divisi on name^st ation #
	14295
	14296	DIVSET^XUS RB2(): Set Division for Curren t User
	14297	Reference Type:Contr olled Subs cription
	14298	Category:U ser
	14299	ICR #:4055
	14300	Descriptio n:This API sets the division f or the cur rent user. (This was developed as a Broke r RPC and all RPCs h ave as the first par ameter the return/ou tput param eter.)
	14301	Format:DIV SET^XUSRB2 (ret,div)
	14302	Input Para meters:ret :(required ) Name of the subscr ipted retu rn array. In every A PI that is used as a n RPC, the first par ameter is the return array.
	14303	div:(requi red) This is the div ision to s elect. If passed wit h a leadin g ` an Int ernal Entr y Number ( IEN) is be ing passed and is pr ocessed as such.
	14304	Output:ret ():Returns a Boolean value in the subscr ipted outp ut array:
	14305	True (non- zero)—Divi sion selec tion is co nsidered s uccessful.
	14306	False (zer o)—Divisio n selectio n failed.
	14307
	14308	USERINFO^X USRB2(): G et Demogra phics for Current Us er
	14309	Reference Type:Contr olled Subs cription
	14310	Category:U ser
	14311	ICR #:4055
	14312	Descriptio n:This API retrieves various u ser demogr aphic info rmation fo r the curr ent user.( This was d eveloped a s a Broker /VistALink RPC and a ll RPCs ha ve as the first para meter the return/out put parame ter.)
	14313	Format:USE RINFO^XUSR B2(ret)
	14314	Input Para meters:ret :(required ) Name of the subscr ipted retu rn array. In every A PI that is used as a n RPC, the first par ameter is the return array.
	14315	Output:ret ():Returns a subscri pted outpu t array:
	14316	RET(1)—Use r’s name f rom the .0 1 field of the NEW P ERSON file (#200).
	14317	RET(2)—Con catenated user name from the N AME COMPON ENTS file (#20).
	14318	RE(3)—Logg ed on divi sion:
	14319	ien^name^n umber
	14320	RET(4)—Use r’s title from the N EW PERSON file (#200 ).
	14321	RET(5)—Use r’s servic e section from NEW P ERSON file (#200, ex ternal for mat).
	14322	RET(6)—Use r’s langua ge from th e NEW PERS ON file (# 200).
	14323	RET(7)—Use r’s timeou t.
	14324
	14325
	14326	XGF Functi on Library : Develope r Tools
	14327	Overview
	14328	The XGF Fu nction Lib rary suppo rts develo pers desig ning text- based appl ications. The functi ons in thi s library support cu rsor posit ioning, ov erlapping text windo ws, video attribute control, a nd keyboar d escape p rocessing, all in a text-mode environmen t.
	14329	If you int end to mak e simple i nterface e nhancement s for an e xisting te xt-mode ap plication, then you may find t he XGF Fun ction Libr ary useful . The XGF Function L ibrary pro vides the following functional ity:
	14330	Text-mode overlappin g windows.
	14331	Text-mode cursor pos itioning b y screen c oordinate.
	14332	Text-mode video attr ibute cont rol (bold, blink, et c.).
	14333	Keyboard r eader usin g M escape processin g (thereby making us e of keyst rokes like <UP-ARROW > (“↑”), < DOWN-ARROW > (“↓”), < PREV> (“←” ), <NEXT> (“→”), etc .).
	14334	The XGF Fu nction Lib rary may n ot be appr opriate if you need:
	14335	A full gra phical use r interfac e (GUI) fr ont end fo r your app lication.
	14336	Support fo r non-ANSI VT-compat ible displ ay devices .
	14337	To use the XGF Funct ion Librar y, your sy stem must use an M i mplementat ion that c omplies wi th the 199 5 ANSI M s tandard. A t a minimu m, the M i mplementat ion must s upport the following features to use the XGF Funct ion Librar y:
	14338	Table 38: XGF Functi on Library —Minimum M implement ation feat ures requi red
	14339	Feature
	14340	Example
	14341	SET into $ EXTRACT
	14342	S X=“this is a strin g”,$E(X,1, 4)=“that”
	14343	Reverse $O RDER
	14344	S X=$O(^TM P(“”),-1)
	14345	Two argume nt $GET
	14346	K Y S X=$G (Y,“DEFAUL T”)
	14347	Skipping p arameters
	14348	D TAG^ROUT INE(,P2,,P 4)
	14349	$NAME
	14350	W $NA(^TMP ($J))
	14351	SET $X and $Y
	14352	S $X=10
	14353
	14354	This XGF F unction Li brary supp orts termi nals that are ANSI-c ompatible and at lea st VT100-c ompatible. As a resu lt, this s oftware do es not sup port QUME QVT102/QVT 102A termi nals.
	14355	REF: The X GF Functio n Library Applicatio n Programm ing Interf aces (APIs ) are docu mented in the “XGF F unction Li brary: Dev eloper Too ls” sectio n in the K ernel Deve loper’s Gu ide. Kerne l and Kern el Toolkit APIs are also avail able in HT ML format on the VA Intranet W ebsite.
	14356	Direct Mod e Utilitie s
	14357	Several XG F Function Library d irect mode utilities are avail able for d evelopers to use at the M prom pt. They a re not API s and cann ot be used in softwa re applica tion routi nes. These direct mo de utiliti es are des cribed bel ow.
	14358	^XGFDEMO: Demo Progr am
	14359	To run an interactiv e demonstr ation show ing the ca pabilities provided by the XGF Function Library, y ou can run the XGF d emo progra m. From th e programm er prompt, type the following:
	14360	>D ^XGFDEM O
	14361	Table 39: XGF Functi on Library —Demo func tional div ision
	14362	Demo Funct ion
	14363	Associated Direct Mo de Utility
	14364	Cursor/Tex t Output
	14365	IOXY^XGF, SAY^XGF, S AYU^XGF
	14366	Video Attr ibutes
	14367	CHGA^XGF, SETA^XGF
	14368	Text Windo ws
	14369	CLEAR^XGF, FRAME^XGF , RESTORE^ XGF, SAVE^ XGF, WIN^X GF
	14370	Keyboard R eader
	14371	$$READ^XGF
	14372	Setup/Clea nup
	14373	CLEAN^XGF, INITKB^XG F, PREP^XG F, RESETKB ^XGF
	14374
	14375	Applicatio n Programm ing Interf ace (API)
	14376	Several AP Is are ava ilable for developer s to work with the X GF Functio n Library. These API s are desc ribed belo w.
	14377	CHGA^XGF() : Screen C hange Attr ibutes
	14378	Reference Type:Suppo rted
	14379	Category:X GF Functio n Library
	14380	ICR #:3173
	14381	Descriptio n:This API changes i ndividual video attr ibutes for subsequen t screen W RITEs.
	14382	Use this A PI to chan ge individ ual video attributes for subse quent outp ut. This A PI is diff erent from SETA^XGF in that in dividual v ideo attri butes can be set wit hout affec ting all v ideo attri butes at o nce.
	14383	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling CHGA ^XGF.
	14384	The attrib ute codes are not ca se sensiti ve. You ca n append t hem if you want to s et more th an one att ribute. If you inclu de more th an one att ribute, th eir order is not imp ortant.
	14385	B0 and B1 turn off a nd on the blink attr ibute.
	14386	I0 and I1 turn off a nd on the intensity attribute.
	14387	R0 and R1 turn off a nd on the reverse at tribute.
	14388	U0 and U1 turn off a nd on the underline attribute.
	14389	E1 turns o ff all att ributes.
	14390	G0 and G1 turn off a nd on reco gnition of an altern ate graphi cs charact er set, so that you can use sp ecial grap hic charac ters, in p articular those set up by Kern el’s GSET^ %ZISS API. To use gr aphics cha racters, b e sure you turn on g raphics fi rst (with G1) and tu rn graphic s off afte rwards (wi th G0).
	14391	The change in attrib ute remain s in effec t until an other CHGA ^XGF, PREP ^XGF(): Sc reen/Keybo ard Setup, or SETA^X GF(): Scre en Video A ttributes API call i s made. If you want only a tem porary cha nge in att ribute, SA Y^XGF may be a bette r function to use.
	14392	Format:CHG A^XGF(atr_ codes)
	14393	Input Para meters:atr _codes:(re quired) Co des are as follows:
	14394	B1—Blink o n.B0—Blink off.
	14395	E1—Turn al l off.
	14396	G1—Graphic s on.G0—Gr aphics off .
	14397	I1—Intensi ty high.I0 —Intensity normal.
	14398	R1—Reverse video on. R0—Reverse video off .
	14399	U1—Underli ne on.U0—U nderline o ff.
	14400	Output Par ameters:xg curatr:Thi s variable always ho lds the cu rrent scre en attribu te coded a s a single character , and is u pdated whe n you call CHGA^XGF.
	14401	$x,$y:Left unchanged .
	14402	REF: See a lso: SETA^ XGF(): Scr een Video Attributes API.
	14403	Examples
	14404	Example 1
	14405	To clear t he screen in blinkin g, reverse video and high inte nsity, do the follow ing:
	14406	>D CHGA^XG F(“R1B1I1” ),CLEAR^XG F(0,0,23,7 9)
	14407
	14408	Example 2
	14409	To print H ello World , do the f ollowing:
	14410	>D CHGA^XG F(“I1”),SA Y^XGF(,,“H ello “)
	14411	>D CHGA^XG F(“U1”),SA Y^XGF(,,“W orld”)
	14412
	14413	Example 3
	14414	To draw th e bottom o f a small box, do th e followin g:
	14415	>D CHGA^XG F(“G1”)
	14416	>D SAY^XGF (,,IOBLC_I OHL_IOHL_I OBRC)
	14417	>D CHGA^XG F(“G0”)
	14418
	14419	CLEAN^XGF: Screen/Ke yboard Exi t and Clea nup
	14420	Reference Type:Suppo rted
	14421	Category:X GF Functio n Library
	14422	ICR #:3173
	14423	Descriptio n:This API exits the XGF scree n and keyb oard envir onments. I t removes XGF screen and keybo ard variab les and ta bles, turn s all vide o attribut es off, tu rns echo o n, turns t he cursor on, and se ts the key pad to num eric mode.
	14424	In additio n, CLEAN^X GF does ev erything t hat the RE SETKB^XGF: Exit XGF Keyboard A PI does to exit the XGF keyboa rd environ ment, incl uding turn ing termin ators and escape pro cessing of f. Subsequ ent READs are proces sed normal ly. If you call CLEA N^XGF, a s eparate ca ll to the RESETKB^XG F: Exit XG F Keyboard API is no t necessar y.
	14425	Format:CLE AN^XGF
	14426	Input Para meters:non e.
	14427	Output:non e.
	14428	REF: See a lso: PREP^ XGF(): Scr een/Keyboa rd Setup A PI.
	14429	CLEAR^XGF( ): Screen Clear Regi on
	14430	Reference Type:Suppo rted
	14431	Category:X GF Functio n Library
	14432	ICR #:3173
	14433	Descriptio n:This API clears a rectangula r region o f the scre en. It is useful to clear a po rtion of t he screen.
	14434	The CLEAR function w orks by pr inting spa ces using the curren t screen a ttribute i n the spec ified regi on. If the screen at tribute is changed a nd then th e CLEAR fu nction is used, the rectangula r region i s cleared in the new attribute .
	14435	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling CLEA R^XGF.
	14436	Acceptable values fo r the top and bottom parameter s range fr om 0 to IO SL-1. Acce ptable val ues for th e left and right par ameters ra nge from 0 to IOM-1.
	14437	Format:CLE AR^XGF(top ,left,bott om,right)
	14438	Input Para meters:top :(required ) Top scre en coordin ate for bo x.
	14439	left:(requ ired) Left screen co ordinate f or box.
	14440	bottom:(re quired) Bo ttom scree n coordina te for box .
	14441	right:(req uired) Rig ht screen coordinate for box.
	14442	Output Par ameters:$x and $y:Se t to the r ight and b ottom spec ified as p arameters.
	14443	REF: See a lso: RESTO RE^XGF(): Screen Res tore, SAVE ^XGF(): Sc reen Save, and WIN^X GF(): Scre en Text Wi ndow APIs.
	14444	Examples
	14445	Example 1
	14446	For exampl e, to clea r the enti re screen, do the fo llowing:
	14447	>D CLEAR^X GF(0,0,23, 79)
	14448
	14449	Example 2
	14450	To clear a rectangul ar region in the cen ter of the screen, d o the foll owing:
	14451	>D CLEAR^X GF(5,20,15 ,60)
	14452
	14453	FRAME^XGF( ): Screen Frame
	14454	Reference Type:Suppo rted
	14455	Category:X GF Functio n Library
	14456	ICR #:3173
	14457	Descriptio n:This API draws a b ox frame o n the scre en. It dis plays boxe s on the s creen.
	14458	The FRAME function d oes not cl ear or oth erwise cha nge the re gion that it encompa sses. If y ou need to open an e mpty frame d window y ou should use the WI N^XGF(): S creen Text Window AP I instead.
	14459	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling FRAM E^XGF.
	14460	Acceptable values fo r the top and bottom parameter s range fr om 0 to IO SL-1. Acce ptable val ues for th e left and right par ameters ra nge from 0 to IOM-1.
	14461	Format:FRA ME^XGF(top ,left,bott om,right)
	14462	Input Para meters:top :(required ) Top scre en coordin ate for bo x.
	14463	left:(requ ired) Left screen co ordinate f or box.
	14464	bottom:(re quired) Bo ttom scree n coordina te for box .
	14465	right:(req uired) Rig ht screen coordinate for box.
	14466	Output Par ameters:$x and $y:Se t to the r ight and b ottom spec ified as p arameters.
	14467	REF: See a lso: RESTO RE^XGF(): Screen Res tore and W IN^XGF(): Screen Tex t Window A PIs.
	14468	Example
	14469	For exampl e, to draw a box in the center of the sc reen, do t he followi ng:
	14470	>D FRAME^X GF(5,20,15 ,60)
	14471
	14472	INITKB^XGF (): Keyboa rd Setup O nly
	14473	Reference Type:Suppo rted
	14474	Category:X GF Functio n Library
	14475	ICR #:3173
	14476	Descriptio n:This API sets up t he XGF key board envi ronment on ly. You sh ould call INITKB^XGF once, bef ore you st art making calls to the $$READ ^XGF funct ion. This API turns on escape processing and any t erminators that are passed.
	14477	Use this A PI only if you are u sing XGF’s Keyboard Reader ind ependently from XGF’ s screen f unctions. Otherwise, a call to the PREP^ XGF(): Scr een/Keyboa rd Setup A PI does ev erything t o set up k eyboard pr ocessing t hat INITKB ^XGF does, and a sep arate call to INITKB ^XGF is no t necessar y.
	14478	Unlike the PREP^XGF( ): Screen/ Keyboard S etup API, INITKB^XGF does not set the ke ypad to ap plication mode.
	14479	INITKB doe s not call %ZISS. Th us, docume nted Kerne l variable s such as IOKPAM and IOKPNM ar e not avai lable for use withou t a separa te call to the ENS^% ZISS: Set Up Screen- handling V ariables A PI.
	14480	Format:INI TKB^XGF([t erm_str])
	14481	Input Para meters:ter m_str:(opt ional) Str ing of cha racters th at should terminate the READ.
	14482	This param eter can b e one of t wo forms:
	14483	A single a sterisk (“ *”) charac ter turns on all ter minators.
	14484	The string of termin ating char acters, su ch as $C(9 ,13,127).
	14485	If this pa rameter is not passe d, or if i t is an em pty string , the term inators ar e not turn ed on.
	14486	Output:non e.
	14487	REF: See a lso: RESET KB^XGF: Ex it XGF Key board API.
	14488	IOXY^XGF() : Screen C ursor Plac ement
	14489	Reference Type:Suppo rted
	14490	Category:X GF Functio n Library
	14491	ICR #:3173
	14492	Descriptio n:This API positions the curso r on the s creen at a screen co ordinate. This API i s similar to Kernel’ s X IOXY f unction. T he row par ameter mus t be betwe en 0 and I OSL-1; the column pa rameter mu st be betw een 0 and IOM- 1.
	14493	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling IOXY ^XGF.
	14494	You can sp ecify row and column parameter s relative to the cu rrent $x a nd $y by s pecifying “+” or “-” to increm ent or dec rement $x or $y by 1 . You can increment or decreme nt by more than one if you add a number as well, s uch as “-5 ” or “+10” .
	14495	NOTE: You must use q uotes to p ass a “+” or “-”. Ot herwise, t o specify exact loca tions for row and co lumn, pass numbers.
	14496	Format:IOX Y^XGF(row, col)
	14497	Input Para meters:row :(required ) Row posi tion to wh ich the cu rsor is mo ved.
	14498	col:(requi red) Colum n position to which the cursor is moved.
	14499	Output Par ameters:$x and $y:Se t to the r ow and col umn specif ied as par ameters.
	14500	REF: See a lso: SAY^X GF(): Scre en String and SAYU^X GF(): Scre en String with Attri butes APIs .
	14501	Example
	14502	For exampl e, to posi tion the c ursor at r ow 12, col umn 39, do the follo wing:
	14503	>D IOXY^XG F(12,39)
	14504
	14505	PREP^XGF() : Screen/K eyboard Se tup
	14506	Reference Type:Suppo rted
	14507	Category:X GF Functio n Library
	14508	ICR #:3173
	14509	Descriptio n:This API sets up t he XGF scr een and ke yboard env ironments.
	14510	Before usi ng any XGF screen fu nctions, y ou must ca ll the PRE P^XGF API. PREP^XGF sets up sc reen contr ol variabl es and tab les. It al so turns o ff all vid eo attribu tes, turns echo off, turns the cursor of f, sets th e keypad t o applicat ion mode, and clears the scree n.
	14511	In additio n, PREP^XG F does eve rything th at the INI TKB^XGF(): Keyboard Setup Only API does to set up the XGF ke yboard env ironment, including turning es cape proce ssing and terminator s on. If y ou call PR EP^XGF, a call to th e INITKB^X GF(): Keyb oard Setup Only API would be r edundant.
	14512	Format:PRE P^XGF(xgcu ratr)
	14513	Input Para meters:non e.
	14514	Output Par ameters:xg curatr:One -character parameter containin g the stat e of the c urrent vid eo attribu te.
	14515	Also, the GSET^%ZISS : Set Up G raphic Var iables API is called , so all o utput vari ables for screen gra phics from GSET^%ZIS S are defi ned.
	14516	REF: See a lso: CLEAN ^XGF: Scre en/Keyboar d Exit and Cleanup A PI.
	14517	$$READ^XGF (): Read U sing Escap e Processi ng
	14518	Reference Type:Suppo rted
	14519	Category:X GF Functio n Library
	14520	ICR #:3173
	14521	Descriptio n:This ext rinsic fun ction prov ides a way to perfor m READs us ing escape processin g. READs, when escap e processi ng is turn ed on, are terminate d by: <UP- ARROW> (“↑ ”), <DOWN- ARROW> (“↓ ”), <PREV> (“←”), <N EXT> (“→”) , <TAB>, a nd other s pecial key strokes.
	14522	$$READ^XGF is a low- level read er compare d to the V A FileMan reader. In some resp ects it is as simple as using the M READ command. This READ function i ncorporate s escape p rocessing, which put s the burd en on the operating system to READ the a rrow, func tion, and all other keys.
	14523	A call to INITKB^XGF or PREP^X GF must be made at s ome point prior to c alling $$R EAD^XGF.
	14524	If the num ber of cha racters yo u request with the f irst param eter is no t entered, the READ does not t erminate u ntil some terminatin g characte r is press ed (or the timeout p eriod is r eached).
	14525	If you do not pass t he timeout parameter , DTIME is used for the timeou t period. If the REA D times ou t, caret ( “^”) is re turned and DTOUT is left defin ed.
	14526	The list o f mnemonic s for keys that can terminate READs is:
	14527	Table 40: XGF Functi on Library —Mnemonics for keys that termi nate READs
	14528	Key Type
	14529	Mnemonic
	14530	Control
	14531	^A, ^B, ^C , ^D, ^E, ^F, ^G, ^H , ^J, ^K, ^L, ^N, ^O , ^P, ^Q, ^R, ^S, ^T , ^U, ^V, ^W, ^X, ^Y , ^Z, ^\, ^], ^6, ^_
	14532	Cursor
	14533	UP, DOWN, RIGHT, LEF T, PREV, N EXT
	14534	Editing
	14535	FIND, INSE RT, REMOVE , SELECT
	14536	Function
	14537	F6 to F14, HELP, DO, F17 to F2 0
	14538	Keyboard
	14539	TAB, CR
	14540	Keypad
	14541	KP0 to KP9 , KP-, KP+ , KP., KPE NTER
	14542	PF
	14543	PF1, PF2, PF3, PF4
	14544
	14545	Format:$$R EAD^XGF([n o_of_char] [,timeout] )
	14546	Input Para meters:no_ of_char:(o ptional) M aximum num ber of cha racters to READ.
	14547	timeout:(o ptional) M aximum dur ation of R EAD, in se conds.
	14548	Output Var iables:XGR T:Set to t he mnemoni c of the k ey that te rminated t he READ.
	14549	REF: For a list of p ossible va lues, see the list b elow or th e table in routine X GKB.
	14550	DTOUT:If d efined, si gnifies th at the REA D timed ou t.
	14551	Output:ret urns:Retur ns the str ing READ f rom the us er.
	14552
	14553	Examples
	14554	Example 1
	14555	To READ a name (with a maximum length of 30) from input and display th at name on the scree n, do the following:
	14556	Figure 144 : SAY^XGF API—Exampl e 1: READ a name
	14557	D INITKB^X GF(“*”)
	14558	W “Name: ” S NM=$$RE AD^XGF(30)
	14559	D SAY^XGF( 10,20,“Hel lo ” NM)
	14560
	14561	Example 2
	14562	To accept only <Up-A rrow> (“↑” ) or <Down -Arrow> (“ ↓”) keys t o exit a r outine, do the follo wing:
	14563	Figure 145 : $$READ^X GF API—Exa mple 2: Ac cept only Up-Arrow ( “↑”) and D own-Arrow (“↓”) keys
	14564	;Only acce pt UP or D OWN arrow keys
	14565	F S %=$$R EAD^XGF(1) Q:XGRT=“U P”!(XGRT=“ DOWN”)
	14566
	14567	NOTE: When you set u p the XGF keyboard e nvironment using INI TKB^XGF ra ther than PREP^XGF, the keypad is not au tomaticall y set to a pplication mode. For READs to be termina ted by the keypad ke ys (<KP0> to <KP9>, <KPENTER>, <KP+>, <K P->, and < KP.>), the keypad mu st be in a pplication mode. You can put t he keypad in applica tion mode by using a n M WRITE statement (W IOKPAM to set app lication m ode, IOKPN M to set n umeric mod e). Take c are to pre serve the value of $ X when usi ng a direc t M WRITE, so that r elative po sitioning in XGF cur sor/text o utput call s is not t hrown off: X=$X W IOK PAM S $X=X
	14568	RESETKB^XG F: Exit XG F Keyboard
	14569	Reference Type:Suppo rted
	14570	Category:X GF Functio n Library
	14571	ICR #:3173
	14572	Descriptio n:This API exits the XGF keybo ard enviro nment. You should us e the RESE TKB^XGF ca ll once yo u finish m aking call s to the $ $READ^XGF( ): Read Us ing Escape Processin g function . The RESE TKB^XGF AP I turns te rminators and escape processin g off and removes an y XGF keyb oard envir onment var iables. Su bsequent R EADs are p rocessed n ormally.
	14573	Use this A PI only if you are u sing XGF’s Keyboard Reader ind ependently from XGF’ s screen f unctions. Otherwise, a call to the CLEAN ^XGF: Scre en/Keyboar d Exit and Cleanup A PI does ev erything t o clean up keyboard processing that the RESETKB^XG F API does , and a se parate cal l to the R ESETKB^XGF API is no t necessar y.
	14574	Unlike the CLEAN^XGF : Screen/K eyboard Ex it and Cle anup API, the RESETK B^XGF API does not s et the key pad to num eric mode.
	14575	Format:RES ETKB^XGF
	14576	Input Para meters:non e.
	14577	Output:non e.
	14578	REF: See a lso: INITK B^XGF(): K eyboard Se tup Only A PI.
	14579	RESTORE^XG F(): Scree n Restore
	14580	Reference Type:Suppo rted
	14581	Category:X GF Functio n Library
	14582	ICR #:3173
	14583	Descriptio n:This API restores a previous ly saved s creen regi on. You ca n save scr een region s using th e WIN^XGF( ): Screen Text Windo w and SAVE ^XGF(): Sc reen Save APIs. REST ORE^XGF re stores the saved scr een region in the sa me screen position a s the scre en region was saved from.
	14584	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling REST ORE^XGF.
	14585	Specify th e array no de under w hich to sa ve the ove rlaid scre en region in closed root and f ully resol ved form ( i.e., clos ed right p arenthesis and with variable r eferences such as $J fully res olved). Us ing M $NAM E function is a quic k way to p ass fully resolved n ode specif ications.
	14586	Format:RES TORE^XGF(s ave_root)
	14587	Input Para meters:sav e_root:(re quired) Gl obal/local array nod e, closed root form.
	14588	Output Par ameters:$x and $y:Se t to the b ottom righ t coordina te of the restored w indow.
	14589	REF: See a lso: CLEAR ^XGF(): Sc reen Clear Region, S AVE^XGF(): Screen Sa ve, and WI N^XGF(): S creen Text Window AP Is.
	14590	Example
	14591	To restore the scree n contents saved to the local array SELE CT to thei r original position, do the fo llowing:
	14592	>D RESTORE ^XGF(“SELE CT”)
	14593
	14594	SAVE^XGF() : Screen S ave
	14595	Reference Type:Suppo rted
	14596	Category:X GF Functio n Library
	14597	ICR #:3173
	14598	Descriptio n:This API saves a s creen regi on. In ord er to save and resto re screen regions, y ou must do all scree n output u sing calls in the XG F Function Library o utput. If you instea d use the M WRITE co mmand for output, th e screen c ontents ca nnot be sa ved and re stored. Al so, a call to the PR EP^XGF(): Screen/Key board Setu p API must be made a t some poi nt prior t o calling SAVE^XGF.
	14599	Specify th e array no de under w hich to sa ve the ove rlaid scre en region in closed root and f ully resol ved form ( i.e., clos ed right p arenthesis and with variable r eferences such as $J fully res olved). Us ing M $NAM E function is a quic k way to p ass fully resolved n ode specif ications.
	14600	Format:SAV E^XGF(top, left,botto m,right,sa ve_root)
	14601	Input Para meters:top :(required ) Top scre en coordin ate for bo x.
	14602	left:(requ ired) Left screen co ordinate f or box.
	14603	bottom:(re quired) Bo ttom scree n coordina te for box .
	14604	right:(req uired) Rig ht screen coordinate for box.
	14605	save_root: (required) Global/lo cal array node, clos ed root fo rm.
	14606	Output Par ameters:$x and $y:Le ft unchang ed.
	14607	REF: See a lso: CLEAR ^XGF(): Sc reen Clear Region, R ESTORE^XGF (): Screen Restore, and WIN^XG F(): Scree n Text Win dow APIs.
	14608	Example
	14609	For exampl e, to save the scree n contents between r ows 5 and 15 and col umns 20 an d 60 in th e SELECT l ocal array , do the f ollowing:
	14610	>D SAVE^XG F(5,20,15, 60,“SELECT ”)
	14611
	14612	SAY^XGF(): Screen St ring
	14613	Reference Type:Suppo rted
	14614	Category:X GF Functio n Library
	14615	ICR #:3173
	14616	Descriptio n:This API outputs a string to the scree n (with op tional pos itioning a nd attribu te control ).
	14617	Use this A PI rather than the M WRITE com mand to ou tput strin gs to the screen. Th e row and column par ameters sp ecify wher e to print the strin g. If omit ted, the c urrent row and colum n position s are used . If speci fied, the row must b e between 0 and IOSL -1, and th e column m ust be bet ween 0 and IOM-1.
	14618	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling SAY^ XGF.
	14619	You can sp ecify row and column parameter s relative to the cu rrent $x a nd $y by s pecifying “+” or “-” to increm ent or dec rement $x or $y by 1 . You can increment or decreme nt by more than 1 if you add a number as well (e.g ., ”-5” or “+10”).
	14620	NOTE: You must use q uotes to p ass a “+” or “-”; ot herwise, t o specify exact loca tions for row and co lumn, pass numbers.
	14621	Without th e fourth a rgument fo r video at tribute, S AY^XGF dis plays the string usi ng the cur rent video attribute . With the fourth ar gument, SA Y^XGF disp lays the s tring usin g the attr ibutes you specify. SAY^XGF ch anges the video attr ibute only for the o utput of t he string; upon term ination of the funct ion, it re stores vid eo attribu tes to the ir state p rior to th e function call.
	14622	REF: For a discussio n of valid video att ribute cod es for the video att ribute par ameter, se e the SETA ^XGF(): Sc reen Video Attribute s API.
	14623	Format:SAY ^XGF([row] [,col,]str [,atr])
	14624	Input Para meters:row :(optional ) Row posi tion to st art WRITE.
	14625	col:(optio nal) Colum n position to start WRITE.
	14626	str:(requi red) Strin g to WRITE .
	14627	atr:(optio nal) Video attribute with whic h to WRITE string.
	14628	REF: For d escription of atr co des, see t he $$READ^ XGF(): Rea d Using Es cape Proce ssing API.
	14629	Output Par ameters:$x and $y:Se t to posit ion of the last char acter outp ut.
	14630	REF: See a lso: IOXY^ XGF(): Scr een Cursor Placement and SAYU^ XGF(): Scr een String with Attr ibutes API s.
	14631	Examples
	14632	Example 1
	14633	For exampl e, to prin t “Hello, World” in the center of the sc reen, in t he current video att ribute, do the follo wing:
	14634	>D SAY^XGF (11,35,“He llo World” )
	14635
	14636	Example 2
	14637	To print “ ERROR!” at (row,col) position ($X+1,$Y+5 ), in reve rse and bo ld video a ttributes, do the fo llowing:
	14638	>D SAY^XGF (“+”,“+5”, “ERROR!”,“ R1B1”)
	14639
	14640	Example 3
	14641	To print “ ...” at th e current cursor pos ition, in the curren t video at tribute, d o the foll owing:
	14642	>D SAY^XGF (,,“...”)
	14643
	14644	SAYU^XGF() : Screen S tring with Attribute s
	14645	Reference Type:Suppo rted
	14646	Category:X GF Functio n Library
	14647	ICR #:3173
	14648	Descriptio n:This API outputs a string to the scree n (with op tional pos ition and attribute control), including the abilit y to under line an in dividual c haracter.
	14649	This API i s similar to SAY^XGF . The diff erence is that the f irst amper sand (“&”) character has a spe cial meani ng in the output str ing; it ac ts as a fl ag to indi cate that the next c haracter s hould be u nderlined. You are o nly allowe d one unde rlined cha racter per call. Typ ically you would use SAYU^XGF when writi ng a menu option’s t ext, in or der to und erline tha t option’s speed key .
	14650	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling SAYU ^XGF.
	14651	You can sp ecify row and column parameter s relative to the cu rrent $x a nd $y by s pecifying “+” or “-” to increm ent or dec rement $x or $y by 1 . You can increment or decreme nt by more than 1 if you add a number as well (e.g ., ”-5” or “+10”).
	14652	NOTE: You must use q uotes to p ass a “+” or “-”. Ot herwise, t o specify exact loca tions for row and co lumn, pass numbers.
	14653	If the fir st ampersa nd is foll owed by an other ampe rsand, thi s initial “&&” is in terpreted and displa yed as one ampersand character , “&”, and you still have the opportunit y to use a single am persand as an underl ining flag .
	14654	Format:SAY U^XGF([row ][,col,]st r[,atr])
	14655	Input Para meters:row :(optional ) Row posi tion to st art WRITE.
	14656	col:(optio nal) Colum n position to start WRITE.
	14657	str:(requi red) Strin g to WRITE (“&” unde rlines nex t characte r).
	14658	atr:(optio nal) Video attribute with whic h to WRITE a string.
	14659	REF: For a descript ion of atr codes, se e the $$RE AD^XGF(): Read Using Escape Pr ocessing A PI.
	14660	Output Par ameters:$x ,$y:Set to the posit ion of the last char acter outp ut.
	14661	REF: See a lso: IOXY^ XGF(): Scr een Cursor Placement and SAY^X GF(): Scre en String APIs.
	14662	Example
	14663	For exampl e, to prin t Save at row 5, col umn 10, do the follo wing:
	14664	>D SAYU^XG F(5,10,“&S ave”)
	14665
	14666	SETA^XGF() : Screen V ideo Attri butes
	14667	Reference Type:Suppo rted
	14668	Category:X GF Functio n Library
	14669	ICR #:3173
	14670	Descriptio n:This API sets all video attr ibute simu ltaneously , for subs equent scr een output . This API is differ ent from t he $$READ^ XGF(): Rea d Using Es cape Proce ssing API in that it takes a d ifferent f orm of the attribute argument, and, unli ke the CHG A^XGF(): S creen Chan ge Attribu tes API, i t sets all attribute s. The cha nge in att ribute rem ains in ef fect until you make another CH GA^XGF(): Screen Cha nge Attrib utes, CLEA N^XGF: Scr een/Keyboa rd Exit an d Cleanup, or SETA^X GF API cal l. If you want only a temporar y change i n attribut e, the SAY ^XGF(): Sc reen Strin g API migh t be a bet ter functi on to use.
	14671	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling the SETA^XGF A PI.
	14672	The value of the att ribute par ameter use s one bit for the va lue of eac h video at tribute. T he format of the bit s is not d ocumented. The curre nt setting of all vi deo attrib utes is ac cessible v ia the xgc uratr para meter, how ever. Rath er than tr ying to us e the SETA ^XGF API t o control an individ ual video attribute’ s setting, you shoul d use it m ainly to r estore the screen at tributes b ased on a previously saved val ue of xgcu ratr.
	14673	Format:SET A^XGF(atr_ code)
	14674	Input Para meters:atr _code:(req uired) Sin gle charac ter contai ning the s tates of a ll video a ttributes as the bit values. T his argume nt itself should be derived fr om a previ ous call t o the PREP ^XGF(): Sc reen/Keybo ard Setup, CHGA^XGF( ): Screen Change Att ributes, o r SETA^XGF APIs.
	14675	Output Par ameters:xg curatr:Thi s paramete r always h olds the c urrent scr een attrib ute coded as a singl e characte r, and is updated wh en you cal l SETA^XGF .
	14676	$x and $y: Left uncha nged.
	14677	REF: See a lso: $$REA D^XGF(): R ead Using Escape Pro cessing AP I.
	14678	Example
	14679	To save th e initial screen att ribute set tings to v ariable SA VEATR, do a function called SO ME^THING, and then r eset all t he video a ttributes to their i nitial sta te, do the following :
	14680	>D PREP^XG F S SAVEAT R=XGCURATR
	14681	>D SOME^TH ING
	14682	>D SETA^XG F(SAVEATR)
	14683
	14684	WIN^XGF(): Screen Te xt Window
	14685	Reference Type:Suppo rted
	14686	Category:X GF Functio n Library
	14687	ICR #:3173
	14688	Descriptio n:This API opens a t ext window on the sc reen and o ptionally remember w hat it ove rlays. If the save r oot parame ter is not passed, y ou cannot restore th e screen b ehind the window.
	14689	In order t o save the screen re gion that the window overlays it is abso lutely nec essary tha t screen o utput is d one using only the f unctions i n the XGF Function l ibrary. If you use t he M WRITE command f or output, the scree n contents cannot be saved.
	14690	A call to the PREP^X GF(): Scre en/Keyboar d Setup AP I must be made at so me point p rior to ca lling WIN^ XGF.
	14691	Specify th e array no de under w hich to sa ve the ove rlaid scre en region in closed root and f ully resol ved form ( i.e., clos ed right p arenthesis and with variable r eferences such as $J fully res olved). Us ing the M $NAME func tion is a quick way to pass fu lly resolv ed node sp ecificatio ns.
	14692	To restore screens y ou save wi th the WIN ^XGF funct ion, use t he RESTORE ^XGF(): Sc reen Resto re API.
	14693	Format:WIN ^XGF(top,l eft,bottom ,right[,sa ve_root])
	14694	Input Para meters:top :(required ) Top scre en coordin ate for bo x.
	14695	left:(requ ired) Left screen co ordinate f or box.
	14696	bottom:(re quired) Bo ttom scree n coordina te for box .
	14697	right:(req uired) Rig ht screen coordinate for box.
	14698	save_root: (optional) Global/lo cal array node, clos ed root fo rm.
	14699	Output Par ameters:sa ve_root:If you speci fy a node as a fifth parameter for save_ root, WIN^ XGF saves the screen region yo u overlay in an arra y at that node.
	14700	$x and $y: Set to the right and bottom co ordinates you specif y as param eters.
	14701	REF: See a lso: CLEAR ^XGF(): Sc reen Clear Region, F RAME^XGF() : Screen F rame, REST ORE^XGF(): Screen Re store, and SAVE^XGF( ): Screen Save APIs.
	14702	Examples
	14703	Example 1
	14704	To draw an empty box in the ce nter of th e screen ( and save t he underly ing screen region un der array SELECT), d o the foll owing:
	14705	>D WIN^XGF (5,20,15,6 0,“SELECT” )
	14706
	14707	Example 2
	14708	To save th e same win dow to a g lobal arra y (to illu strate the use of $N AME to spe cify a ful ly resolve d root), d o the foll owing:
	14709	>D WIN^XGF (5,20,15,6 0,$NA(^TMP ($J)))
	14710
	14711
	14712	XLF Functi on Library : Develope r Tools
	14713	Overview
	14714	Several AP Is are ava ilable for developer s to work with the X LF Functio n Library. These API s are desc ribed belo w.
	14715	The XLF Fu nction Lib rary provi des the fo llowing fu nctions:
	14716	CRC Functi ons—XLFCRC .
	14717	Date Funct ions—XLFDT .
	14718	Hyperbolic Trigonome tric Funct ions—XLFHY PER.
	14719	IP Address Functions —XLFIPV.
	14720	Mathematic al Functio ns—XLFMTH.
	14721	Measuremen t Function s—XLFMSMT.
	14722	String Fun ctions—XLF STR.
	14723	Utility Fu nctions—XL FUTL.
	14724	Applicatio n Programm ing Interf ace (API)
	14725
	14726	CRC Functi ons—XLFCRC
	14727	These func tions are provided t o help pro cess strin gs.
	14728	$$CRC16^XL FCRC(): Cy clic Redun dancy Code 16
	14729	Reference Type:Suppo rted
	14730	Category:C RC Functio ns
	14731	ICR #:3156
	14732	Descriptio n:This ext rinsic fun ction comp utes a Cyc lic Redund ancy Code (CRC) of t he 8-bit c haracter s tring, usi ng X^16 + X^15 + X^2 + 1 as th e polynomi al. The op tional par ameter “se ed” can su pply an in itial valu e, which a llows for running CR C calculat ions on mu ltiple str ings. If t he paramet er “seed” is not spe cified, a default va lue of zer o (0) is a ssumed. Th e value of “seed” is limited t o 0 <= see d <= 2^16. The funct ion value is between 0 and 2^1 6.
	14733	Format:$$C RC16^XLFCR C(string[, seed])
	14734	Input Para meters:str ing:(requi red) Strin g upon whi ch to comp ute the CR C16.
	14735	seed:(opti onal) Seed value. Ne eded to co mpute the CRC16 over multiple strings.
	14736	Output:ret urns:Retur ns the Cyc lic Redund ancy Code (CRC) 16 v alue.
	14737
	14738	Examples
	14739	Example 1
	14740	SET CRC=$$ CRC16^XLFC RC(string)
	14741	A checksum can also be calcula ted over m ultiple st rings.
	14742	Figure 146 : $$CRC16^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (1 of 2)
	14743	SET (I,C)= 0
	14744	FOR SET I =$ORDER(X( I)) QUIT:’ I DO
	14745	. SET C=$$ CRC16^XLFC RC(X(I),C)
	14746
	14747	Or:
	14748
	14749	Figure 147 : $$CRC16^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (2 of 2)
	14750	SET I=0,C= 4294967295
	14751	FOR SET I =$ORDER(X( I)) QUIT:’ I DO
	14752	. SET C=$$ CRC16^XLFC RC(X(I),C)
	14753
	14754	As long as the save method is used all t he time.
	14755	Example 2
	14756	Figure 148 : $$CRC16^ XLFCRC API —Example 2
	14757	CRC162 ;Te st call CR C16^XLFCRC multiple times
	14758	S TEXT=“No w is the t ime for al l good chi ldren”,TEX T2=“to com e to the a id of thei r country. ”
	14759	S CRC=0,CR C=$$CRC16^ XLFCRC(TEX T,CRC)
	14760	If 23166=$ $CRC16^XLF CRC(TEXT2, CRC) WRITE !,“CRC16 OK”
	14761	Q
	14762
	14763	NOTE: Thes e have bee n approved for inclu sion in a future ANS I M langua ge standar d as part of the lib rary.
	14764	$$CRC32^XL FCRC(): Cy clic Redun dancy Code 32
	14765	Reference Type:Suppo rted
	14766	Category:C RC Functio ns
	14767	ICR #:3156
	14768	Descriptio n:This ext rinsic fun ction comp utes a Cyc lic Redund ancy Code (CRC) of t he 8-bit c haracter s tring, usi ng X^32 + X^26 + X^2 3 + X^22 + X^16 + X^ 12 + X^11 + X^10 + X ^8 + X^7 + X^5 + X^4 + X^2 + X + 1 as th e polynomi al. The op tional par ameter “se ed” can su pply an in itial valu e, which a llows for running CR C calculat ions on mu ltiple str ings. If t he paramet er “seed” is not spe cified, a default va lue of 4,2 94,967,295 (2^32-1) is assumed . The valu e of “seed ” is limit ed to 0 <= seed <= 2 ^32. The f unction va lue is bet ween 0 and 2^32.
	14769	Format:$$C RC32^XLFCR C(string[, seed])
	14770	Input Para meters:str ing:(requi red) Strin g upon whi ch to comp ute the CR C32.
	14771	seed:(opti onal) Seed value. Ne eded to co mpute the CRC32 over multiple strings.
	14772	Output:ret urns:Retur ns the Cyc lic Redund ancy Code (CRC) 32 v alue.
	14773
	14774	Examples
	14775	Example 1
	14776	SET CRC=$$ CRC32^XLFC RC(string)
	14777
	14778	A checksum can also be calcula ted over m ultiple st rings.
	14779	Figure 149 : $$CRC32^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (1 of 2)
	14780	SET (I,C)= 0
	14781	FOR SET I =$ORDER(X( I)) QUIT:’ I DO
	14782	. SET C=$$ CRC32^XLFC RC(X(I),C)
	14783
	14784	Or:
	14785	Figure 150 : $$CRC32^ XLFCRC API —Example 1 : Calculat ing a chec ksum over multiple s trings (2 of 2)
	14786	SET I=0,C= 4294967295
	14787	FOR SET I =$ORDER(X( I)) QUIT:’ I DO
	14788	. SET C=$$ CRC32^XLFC RC(X(I),C)
	14789
	14790	As long as the save method is used all t he time.
	14791	Example 2
	14792	Figure 151 : $$CRC32^ XLFCRC API —Example 2
	14793	CRC322 ;Te st call CR C32^XLFCRC multiple times
	14794	S TEXT=“No w is the t ime for al l good chi ldren”,TEX T2=“to com e to the a id of thei r country. ”
	14795	S CRC=0,CR C=$$CRC32^ XLFCRC(TEX T,CRC)
	14796	If 7158202 30=$$CRC32 ^XLFCRC(TE XT2,CRC) W RITE !,“CR C32 OK”
	14797	Q
	14798
	14799	NOTE: Thes e have bee n approved for inclu sion in a future ANS I M langua ge standar d as part of the lib rary.
	14800	Date Funct ions—XLFDT
	14801	$$%H^XLFDT (): Conver t Seconds to $H
	14802	Reference Type:Suppo rted
	14803	Category:D ate Functi ons
	14804	ICR #:1010 3
	14805	Descriptio n:This ext rinsic fun ction conv erts the n umber of s econds inp ut to a $H formatted date. It converts t he output of the $$S EC^XLFDT() : Convert $H/VA File Man date t o Seconds API back t o a $H val ue.
	14806	Format:$$% H^XLFD(sec onds)
	14807	Input Para meters:sec onds:(requ ired) Inpu t seconds.
	14808	Output:ret urns:Retur ns seconds in $H dat e format.
	14809
	14810	Example
	14811	>S X=$$%H^ XLFDT(5108 536020)
	14812
	14813	>W X
	14814	59126,4962 0
	14815
	14816	$$DOW^XLFD T(): Day o f Week
	14817	Reference Type:Suppo rted
	14818	Category:D ate Functi ons
	14819	ICR #:1010 3
	14820	Descriptio n:This ext rinsic fun ction retu rns the co rrespondin g day of t he week fr om a date in VA File Man format .
	14821	Format:$$D OW^XLFD(x[ ,y])
	14822	Input Para meters:x:( required) VA FileMan date.
	14823	y:(optiona l) 1 to re turn a day -of-week n umber.
	14824	Output:ret urns:Retur ns the day of the we ek.
	14825
	14826	Examples
	14827	Example 1
	14828	>S X=$$DOW ^XLFDT(290 1231.11152 3)
	14829
	14830	>W X
	14831	Monday
	14832
	14833	Example 2
	14834	>S X=$$DOW ^XLFDT(290 1231.11152 3,1)
	14835
	14836	>W X
	14837	1
	14838
	14839	$$DT^XLFDT : Current Date (VA F ileMan Dat e Format)
	14840	Reference Type:Suppo rted
	14841	Category:D ate Functi ons
	14842	ICR #:1010 3
	14843	Descriptio n:This ext rinsic fun ction retu rns the cu rrent date in VA Fil eMan forma t.
	14844	Format:$$D T^XLFDT
	14845	Input Para meters:non e.
	14846	Output:ret urns:Retur ns the cur rent date in VA File Man format .
	14847
	14848	Example
	14849	>S X=$$DT^ XLFDT
	14850
	14851	>W X
	14852	3040126
	14853
	14854	$$FMADD^XL FDT(): VA FileMan Da te Add
	14855	Reference Type:Suppo rted
	14856	Category:D ate Functi ons
	14857	ICR #:1010 3
	14858	Descriptio n:This ext rinsic fun ction retu rns the re sult of ad ding days, hours, mi nutes, and seconds t o a date i n VA FileM an format.
	14859	Format:$$F MADD^XLFDT (x,d,h,m,s )
	14860	Input Para meters:x:( required) VA FileMan date (in quotes).
	14861	d:(require d) Days.
	14862	h:(require d) Hours.
	14863	m:(require d) Minutes .
	14864	s:(require d) Seconds .
	14865	Output:ret urns:Retur ns the upd ated date and time i n VA FileM an format.
	14866
	14867	Example
	14868	>S X=$$FMA DD^XLFDT(2 901231.01, 2,2,20,15)
	14869
	14870	>W X
	14871	2910102.03 2015
	14872
	14873	$$FMDIFF^X LFDT(): VA FileMan D ate Differ ence
	14874	Reference Type:Suppo rted
	14875	Category:D ate Functi ons
	14876	ICR #:1010 3
	14877	Descriptio n:This ext rinsic fun ction retu rns the di fference b etween two VA FileMa n format d ates.
	14878	Format:$$F MDIFF^XLFD T(x1,x2[,x 3])
	14879	Input Para meters:x1: (required) VA FileMa n date.
	14880	x2:(requir ed) VA Fil eMan date, to subtra ct from th e x1 date.
	14881	x3:(option al) If nul l (‘$D(x3) , return t he differe nce in day s. Otherwi se:
	14882	If x3 = 1, return th e differen ce in days .
	14883	If x3 = 2, return th e differen ce in seco nds.
	14884	If x3 = 3, return th e differen ce in days hours:min utes:secon ds format (DD HH:MM: SS).
	14885	Output:ret urns:Retur ns the dat e and/or t ime differ ence.
	14886
	14887	Examples
	14888	Example 1
	14889	The follow ing exampl e returns the differ ence betwe en two dat es/times i n days (x3 = null or 1). In th is example , the firs t date is 2 days les s than the second da te:
	14890	>S X=$$FMD IFF^XLFDT( 2901229,29 01231.1115 23)
	14891
	14892	>W X
	14893	-2
	14894
	14895	>S X=$$FMD IFF^XLFDT( 2901229,29 01231.1115 23,1)
	14896
	14897	>W X
	14898	-2
	14899
	14900	Example 2
	14901	The follow ing exampl e returns the differ ence betwe en two dat es/times i n seconds (x3 = 2). In this ex ample, the first dat e is 150,0 79 seconds greater t han the se cond date:
	14902	>S X=$$FMD IFF^XLFDT( 2901231.11 1523,29012 29.173404, 2)
	14903
	14904	>W X
	14905	150079
	14906
	14907	Example 3
	14908	The follow ing exampl e returns the differ ence betwe en two dat es/times i n DD HH:MM :SS (x3 = 3). In thi s example, the first date is 1 day, 1 ho ur, 24 min utes, and 2 seconds greater th an the sec ond date:
	14909	>S X=$$FMD IFF^XLFDT( 2901231.02 4703,29012 30.012301, 3)
	14910
	14911	>W X
	14912	1 1:24:2
	14913
	14914	$$FMTE^XLF DT(): Conv ert VA Fil eMan Date to Externa l Format
	14915	Reference Type:Suppo rted
	14916	Category:D ate Functi ons
	14917	ICR #:1010 3
	14918	Descriptio n:This ext rinsic fun ction conv erts a VA FileMan fo rmatted in put date t o an exter nal format ted date.
	14919	Format:$$F MTE^XLFDT( x[,y])
	14920	Input Para meters:x:( required) VA FileMan date.
	14921	y:(optiona l) Affects output as follows:
	14922	If null, ‘ $D(y), ret urn the wr itten-out format.
	14923	If ‘$D(y) then retur n standard VA FileMa n format.
	14924	If +y = 1 then retur n standard VA FileMa n format.
	14925	If +y = 2 then retur n MM/DD/YY @HH:MM:SS format.
	14926	If +y = 3 then retur n DD/MM/YY @HH:MM:SS format.
	14927	If +y = 4 then retur n YY/MM/DD @HH:MM:SS format.
	14928	If +y = 5 then retur n MM/DD/YY YY@HH:MM:S S format.
	14929	If +y = 6 then retur n DD/MM/YY YY@HH:MM:S S format.
	14930	If +y = 7 then retur n YYYY/MM/ DD@HH:MM:S S format.
	14931	If y conta ins a “D” then date only.
	14932	If y conta ins an “F” then outp ut date wi th leading spaces.
	14933	If y conta ins an “M” then only output “H H:MM”.
	14934	If y conta ins a “P” then outpu t “HH:MM:S S am/pm”.
	14935	If y conta ins an “S” then forc e seconds in the out put.
	14936	If y conta ins a “Z” then outpu t date wit h leading zeroes.
	14937	Output:ret urns:Retur ns the ext ernal form atted date .
	14938
	14939	Examples
	14940	Example 1
	14941	Return the date in t he followi ng format: Standard VA FileMan date form at.
	14942	>S X=$$FMT E^XLFDT(29 40629.1057 44,1)
	14943
	14944	>W X
	14945	Jun 29, 19 94@10:57:4 4
	14946
	14947	Example 2
	14948	Return the date in t he followi ng format: Standard VA FileMan date form at and inc lude am/pm .
	14949	>S X=$$FMT E^XLFDT(29 40629.1057 ,“1P”)
	14950
	14951	>W X
	14952	Jun 29, 19 94 10:57 a m
	14953
	14954	Example 3
	14955	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS.
	14956	>S X=$$FMT E^XLFDT(29 40629.1057 44,2)
	14957
	14958	>W X
	14959	6/29/94@10 :57:44
	14960
	14961	Example 4
	14962	Return the date in t he followi ng format: MM/DD/YY@ HH:MM.
	14963	>S X=$$FMT E^XLFDT(29 40629.1057 44,“2M”)
	14964
	14965	>W X
	14966	6/29/94@10 :57
	14967
	14968	Example 5
	14969	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS a nd include am/pm.
	14970	>S X=$$FMT E^XLFDT(29 40629.1057 44,“2P”)
	14971
	14972	>W X
	14973	6/29/94 10 :57:44 am
	14974
	14975	Example 6
	14976	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS, forcing se conds to d isplay whe n no secon ds were in cluded in the input parameter.
	14977	>S X=$$FMT E^XLFDT(29 40629.1057 ,“2S”)
	14978
	14979	>W X
	14980	6/29/94@10 :57:00
	14981
	14982	Example 7
	14983	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS, forcing se conds to d isplay whe n no secon ds were in cluded in the input parameter, and inclu de leading spaces.
	14984	>S X=$$FMT E^XLFDT(29 40629.1057 ,“2SF”)
	14985
	14986	>W X
	14987	6/29/94@1 0:57:00
	14988
	14989	Example 8
	14990	Return the date in t he followi ng format: DD/MM/YY@ HH:MM:SS a nd include leading s paces.
	14991	>S X=$$FMT E^XLFDT(29 40629.1057 44,“3F”)
	14992
	14993	>W X
	14994	29/ 6/94@1 0:57:44
	14995
	14996	Example 9
	14997	Return the date in t he followi ng format: YY/MM/DD, ignore th e time val ues entere d and only display t he date.
	14998	>S X=$$FMT E^XLFDT(29 40629.1057 ,“4D”)
	14999
	15000	>W X
	15001	94/6/29
	15002
	15003	Example 10
	15004	To output a really s hort date/ time try t he followi ng, conver t space to zero and remove sla sh, as sho wn below:
	15005	>S X=$TR($ $FMTE^XLFD T(2940629. 1057,“4F”) ,“ /”,“0”)
	15006
	15007	>W X
	15008	940629@10: 57
	15009
	15010	Example 11
	15011	Return the date in t he followi ng format: MM/DD/YYY Y@HH:MM:SS .
	15012	>S X=$$FMT E^XLFDT(30 00229.1105 20,5)
	15013
	15014	>W X
	15015	2/29/2000@ 11:05:20
	15016
	15017	Example 12
	15018	Return the date in t he followi ng format: MM/DD/YYY Y@HH:MM:SS and inclu de leading spaces.
	15019	>S X=$$FMT E^XLFDT(30 00229.1105 20,“5F”)
	15020
	15021	>W X
	15022	2/29/2000 @11:05:20
	15023
	15024	Example 13
	15025	Return the date in t he followi ng format: MM/DD/YYY Y@HH:MM:SS , forcing seconds.
	15026	>S X=$$FMT E^XLFDT(30 00229.1105 ,“5S”)
	15027
	15028	>W X
	15029	2/29/2000@ 11:05:00
	15030
	15031	Example 14
	15032	Return the date in t he followi ng format: MM/DD/YYY Y HH:MM:SS , include leading ze roes, and include am /pm.
	15033	>S X=$$FMT E^XLFDT(30 00229.1105 20,“5ZP”)
	15034
	15035	>W X
	15036	02/29/2000 11:05:20 am
	15037
	15038	Example 15
	15039	Return the date in t he followi ng format: DD/MM/YYY Y@HH:MM:SS , with lea ding space s.
	15040	>S X=$$FMT E^XLFDT(30 00229.1105 20,“6F”)
	15041
	15042	>W X
	15043	29/ 2/2000 @11:05:20
	15044
	15045	Example 16
	15046	Return the date in t he followi ng format: DD/MM/YYY Y@HH:MM:SS , with lea ding zeroe s.
	15047	>S X=$$FMT E^XLFDT(30 00229.1105 ,“6Z”)
	15048
	15049	>W X
	15050	29/02/2000 @11:05
	15051
	15052	Example 17
	15053	Return the date in t he followi ng format: YYYY/MM/D D@HH:MM:SS .
	15054	>S X=$$FMT E^XLFDT(30 00301.1105 ,7)
	15055
	15056	>W X
	15057	2000/3/1@1 1:05
	15058
	15059	Example 18
	15060	Return the date in t he followi ng format: YYYY/MM/D D, ignore the time v alues ente red and on ly display the date.
	15061	>S X=$$FMT E^XLFDT(30 00301.1105 ,“7D”)
	15062
	15063	>W X
	15064	2000/3/1
	15065
	15066	$$FMTH^XLF DT(): Conv ert VA Fil eMan Date to $H
	15067	Reference Type:Suppo rted
	15068	Category:D ate Functi ons
	15069	ICR #:1010 3
	15070	Descriptio n:This ext rinsic fun ction conv erts a VA FileMan fo rmatted in put date t o a $H for matted dat e.
	15071	Format:$$F MTH^XLFDT( x[,y])
	15072	Input Para meters:x:( required) VA FileMan date.
	15073	y:(optiona l) 1 to re turn the d ate portio n only (no seconds).
	15074	Output:ret urns:Retur ns the con verted dat e in $H fo rmat.
	15075
	15076	Examples
	15077	Example 1
	15078	>S X=$$FMT H^XLFDT(29 01231.1115 23)
	15079
	15080	>W X
	15081	54786,4052 3
	15082
	15083	Example 2
	15084	>S X=$$FMT H^XLFDT(29 01231.1115 23,1)
	15085
	15086	>W X
	15087	54786
	15088
	15089	$$FMTHL7^X LFDT(): Co nvert VA F ileMan Dat e to HL7 D ate
	15090	Reference Type:Suppo rted
	15091	Category:D ate Functi ons
	15092	ICR #:1010 3
	15093	Descriptio n:This ext rinsic fun ction conv erts a VA FileMan fo rmatted in put date/t ime into a n HL7 form atted date , includin g the time offset.
	15094	Format:$$F MTHL7^XLFD T(fm_date_ time)
	15095	Input Para meters:fm_ date_time: (required) VA FileMa n date.
	15096	Output:ret urns:Retur ns the con verted dat e in HL7 f ormat.
	15097
	15098	Example
	15099	>S X=$$FMT HL7^XLFDT( 3001127.15 25)
	15100
	15101	>W X
	15102	2000112715 25-0800
	15103
	15104	$$HADD^XLF DT(): $H A dd
	15105	Reference Type:Suppo rted
	15106	Category:D ate Functi ons
	15107	ICR #:1010 3
	15108	Descriptio n:This ext rinsic fun ction retu rns the re sult of ad ding days, hours, mi nutes, and seconds t o a date i n $H forma t.
	15109	Format:$$H ADD^XLFDT( x,d,h,m,s)
	15110	Input Para meters:x:( required) $H date (i n quotes).
	15111	d:(require d) Days.
	15112	h:(require d) Hours.
	15113	m:(require d) Minutes .
	15114	s:(require d) Seconds .
	15115	Output:ret urns:Retur ns the res ultant dat e in $H fo rmat.
	15116
	15117	Example
	15118	>S X=$$HAD D^XLFDT(“5 4786,3600” ,2,2,20,15 )
	15119
	15120	>W X
	15121	54788,1201 5
	15122
	15123	$$HDIFF^XL FDT(): $H Difference
	15124	Reference Type:Suppo rted
	15125	Category:D ate Functi ons
	15126	ICR #:1010 3
	15127	Descriptio n:This ext rinsic fun ction retu rns the di fference b etween two $H format ted dates.
	15128	Format:$$H DIFF^XLFDT (x1,x2[,x3 ])
	15129	Input Para meters:x1: (required) $H date ( in quotes) .
	15130	x2:(requir ed) $H dat e (in quot es) to sub tract from the x1 da te.
	15131	x3:(option al) If nul l (‘$D(x3) , return t he differe nce in day s. Otherwi se:
	15132	If x3 = 1, return th e differen ce in days .
	15133	If x3 = 2, return th e differen ce in seco nds.
	15134	If x3 = 3, return th e differen ce in days hours:min utes:secon ds format (DD HH:MM: SS).
	15135	Output:ret urns:Retur ns the $H difference .
	15136
	15137	Examples
	15138	Example 1
	15139	Return the &H differ ence in da ys.
	15140	>S X=$$HDI FF^XLFDT(“ 54789,4052 3”,“54786, 25983”,1)
	15141
	15142	>W X
	15143	3
	15144
	15145	Example 2
	15146	Return the &H differ ence in se conds.
	15147	>S X=$$HDI FF^XLFDT(“ 54789,4052 3”,“54786, 25983”,2)
	15148
	15149	>W X
	15150	273740
	15151
	15152	Example 3
	15153	Return the &H differ ence in da ys hours:m inutes:sec onds forma t (DD HH:M M:SS).
	15154	>S X=$$HDI FF^XLFDT(“ 54789,4052 3”,“54786, 25983”,3)
	15155
	15156	>W X
	15157	3 4:02:20
	15158
	15159	$$HL7TFM^X LFDT(): Co nvert HL7 Date to VA FileMan D ate
	15160	Reference Type:Suppo rted
	15161	Category:D ate Functi ons
	15162	ICR #:1010 3
	15163	Descriptio n:This ext rinsic fun ction conv erts an HL 7 formatte d input da te/time in to a VA Fi leMan form atted date /time.
	15164	Format:$$H L7TFM^XLFD T(hl7_date _time[,loc al_uct][,t ime_flag])
	15165	Input Para meters:hl7 _date_time :(required ) HL7 form atted date and time.
	15166	local_uct: (optional) This para meter cont rols if an y time off set is app lied to th e time. If a time of fset is in cluded, th en time of fset can b e applied to give Lo cal time o r Coordina ted Univer sal Time ( UTC, a.k.a . GMT, or Greenwich Mean Time) time offs et from th e MAILMAN TIME ZONE file (#4.4 ). The def ault is to return Lo cal time. Valid valu es are:
	15167	L (default )—Local ti me.
	15168	U—UTC time .
	15169	time_flag: (optional) This para meter is s et to 1 if the value in the hl 7_date_tim e input pa rameter is just a ti me value. The defaul t assumes that the h l7_date_ti me input p arameter i s a date a nd time va lue.
	15170	Output:ret urns:Retur ns the con verted dat e in VA Fi leMan form at.
	15171
	15172	Examples
	15173	Example 1
	15174	To get dat e with no offset:
	15175	>S X=$$HL7 TFM^XLFDT( “200011271 525-0700”)
	15176
	15177	>W X
	15178	3001127.15 25
	15179
	15180	Example 2
	15181	To get UTC time offs et:
	15182	>S X=$$HL7 TFM^XLFDT( “200011271 525-0700”, “U”)
	15183
	15184	>W X
	15185	3001127.22 25
	15186
	15187	Example 3
	15188	To get Loc al time in PST offse t:
	15189	>S X=$$HL7 TFM^XLFDT( “200011271 525-0700”, “L”)
	15190
	15191	>W X
	15192	3001127.14 25
	15193
	15194	Example 4
	15195	To get Loc al time wh en only pr oviding a time (no d ate) as th e input pa rameter:
	15196	>S X=$$HL7 TFM^XLFDT( “1525-0700 ”,“L”,1)
	15197
	15198	>W X
	15199	.1525
	15200
	15201	$$HTE^XLFD T(): Conve rt $H to E xternal Fo rmat
	15202	Reference Type:Suppo rted
	15203	Category:D ate Functi ons
	15204	ICR #:1010 3
	15205	Descriptio n:This ext rinsic fun ction conv erts a $H formatted input date to an ext ernal form atted date .
	15206	Format:$$H TE^XLFDT(x [,y])
	15207	Input Para meters:x:( required) $H date (i n quotes).
	15208	y:(optiona l) Affects output as follows:
	15209	If null (‘ $D(y)) ret urn the wr itten-out format.
	15210	If ‘$D(y) then retur n standard VA FileMa n format.
	15211	If +y = 1 then retur n standard VA FileMa n format.
	15212	If +y = 2 then retur n MM/DD/YY @HH:MM:SS format.
	15213	If +y = 3 then retur n DD/MM/YY @HH:MM:SS format.
	15214	If +y = 4 then retur n YY/MM/DD @HH:MM:SS format.
	15215	If +y = 5 then retur n MM/DD/YY YY@HH:MM:S S format.
	15216	If +y = 6 then retur n DD/MM/YY YY@HH:MM:S S format.
	15217	If +y = 7 then retur n YYYY/MM/ DD@HH:MM:S S format.
	15218	If y conta ins a “D” then date only.
	15219	If y conta ins an “F” then outp ut date wi th leading blanks.
	15220	If y conta ins an “M” then outp ut “HH:MM” only.
	15221	If y conta ins a “P” then outpu t “HH:MM:S S am/pm”.
	15222	If y conta ins an “S” then forc e seconds in the out put.
	15223	If y conta ins a “Z” then outpu t date wit h leading zeroes.
	15224	Output:ret urns:Retur ns the ext ernal form at of a $H date.
	15225
	15226	Examples
	15227	Example 1
	15228	Return the date in t he followi ng format: Standard external f ormat.
	15229	>S X=$$HTE ^XLFDT(“54 786,40523” )
	15230
	15231	>W X
	15232	Dec 31, 19 90@11:15:2 3
	15233
	15234	Example 2
	15235	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS.
	15236	>S X=$$HTE ^XLFDT(“54 786,40523” ,2)
	15237
	15238	>W X
	15239	12/31/90@1 1:15:23
	15240
	15241	Example 3
	15242	Return the date in t he followi ng format: MM/DD/YY@ HH:MM:SS, omitting t he seconds .
	15243	>S X=$$HTE ^XLFDT(“57 386,33723” ,“2M”)
	15244
	15245	>W X
	15246	2/12/98@09 :22
	15247
	15248	Example 4
	15249	Return the date in t he followi ng format: MM/DD/YYY Y@HH:MM:SS .
	15250	>S X=$$HTE ^XLFDT(“57 351,27199” ,5)
	15251
	15252	>W X
	15253	1/8/1998@0 7:33:19
	15254
	15255	Example 5
	15256	Return the date in t he followi ng format: DD/MM/YYY Y@HH:MM:SS .
	15257	>S X=$$HTE ^XLFDT(“57 351,27199” ,6)
	15258
	15259	>W X
	15260	8/1/1998@0 7:33:19
	15261
	15262	Example 6
	15263	Return the date in t he followi ng format: YYYY/MM/D D@HH:MM:SS .
	15264	>S X=$$HTE ^XLFDT(“57 351,27199” ,7)
	15265
	15266	>W X
	15267	1998/1/8@0 7:33:19
	15268
	15269	$$HTFM^XLF DT(): Conv ert $H to VA FileMan Date Form at
	15270	Reference Type:Suppo rted
	15271	Category:D ate Functi ons
	15272	ICR #:1010 3
	15273	Descriptio n:This ext rinsic fun ction conv erts a $H formatted input date to a VA F ileMan for matted dat e.
	15274	Format:$$H TFM^XLFDT( x[,y])
	15275	Input Para meters:x:( required) $H date (i n quotes).
	15276	y:(optiona l) 1 to re turn the d ate portio n only (no seconds).
	15277	Output:ret urns:Retur ns the con verted $H date in VA FileMan f ormat.
	15278
	15279	Examples
	15280	Example 1
	15281	>S X=$$HTF M^XLFDT(“5 4786,40523 ”)
	15282
	15283	>W X
	15284	2901231.11 1523
	15285
	15286	Example 2
	15287	>S X=$$HTF M^XLFDT(“5 4786,40523 ”,1)
	15288
	15289	>W X
	15290	2901231
	15291
	15292	$$NOW^XLFD T: Current Date and Time (VA F ileMan For mat)
	15293	Reference Type:Suppo rted
	15294	Category:D ate Functi ons
	15295	ICR #:1010 3
	15296	Descriptio n:This ext rinsic fun ction retu rns the cu rrent date and time in VA File Man format .
	15297	Format:$$N OW^XLFDT
	15298	Input Para meters:non e.
	15299	Output:ret urns:Retur ns the cur rent date and time i n VA FileM an format.
	15300
	15301	Example
	15302	>S X=$$NOW ^XLFDT
	15303
	15304	>W X
	15305	3040126.10 3044
	15306
	15307	$$SCH^XLFD T(): Next Scheduled Runtime
	15308	Reference Type:Suppo rted
	15309	Category:D ate Functi ons
	15310	ICR #:1010 3
	15311	Descriptio n:This ext rinsic fun ction retu rns the ne xt run-tim e based on Schedule code.
	15312	Format:$$S CH^XLFDT(s chedule_st ring,base_ date[,forc e_future_f lag])
	15313	Input Para meters:sch edule_stri ng:(requir ed) Interv al to add to base_da te, as fol lows:
	15314	nS—Add n s econds to base_date.
	15315	nH—Add n h ours to ba se_date.
	15316	nD—Add n d ays to bas e_date.
	15317	nM—Add n m onths to b ase_date.
	15318	$H;$H;$H—L ist of $H dates.
	15319	nM(list)—C omplex mon th increme nt. For ex ample: 1M( 15,L), whi ch means s chedule it to run ev ery month (1M) on th e 15 and l ast day of the month (15,L).
	15320	dd[@time]— Day of mon th (e.g., 12).
	15321	nDay[@time ]—day of w eek in mon th (e.g., 1M, first Monday); ( see “Day C ode“ list that follo ws).
	15322	Day.
	15323	L—Last day of month.
	15324	LDay—Last specific d ay in mont h (e.g., L M [last Mo nday],LT [ last Tuesd ay],LW [la st Wednesd ay]...).
	15325	Day[@time] —Day of we ek (see “D ay Code “ list that follows).
	15326	Day.
	15327	D—Every we ekday.
	15328	E—Every we ekend day (Saturday, Sunday).
	15329	Day Code ( used in sc hedule cod es above):
	15330	M—Monday
	15331	T—Tuesday
	15332	W—Wednesda y
	15333	R—Thursday
	15334	F—Friday
	15335	S—Saturday
	15336	U—Sunday
	15337	base_date: (required) VA FileMa n date to which the interval i s added.
	15338	force_futu re_flag:(o ptional) I f passed w ith a valu e of:
	15339	1—Forces r eturned da te to be i n future, by repeate dly adding interval to base_da te until a future da te is prod uced.
	15340	Otherwise— Interval i s added on ce.
	15341	Output:ret urns:Retur ns the nex t run-time .
	15342
	15343	Examples
	15344	Example 1
	15345	To schedul e somethin g to run e very month on the 15 th of the month at 2 :00 p.m. a nd on the last day o f every mo nth at 6:0 0 p.m., yo u would en ter the fo llowing:
	15346	Middle of the Month:
	15347	>S X=$$SCH ^XLFDT(“1M (15@2PM,L@ 6PM)”,2931 003)
	15348
	15349	>W X
	15350	2931015.14
	15351	End of the Month:
	15352	>S X=$$SCH ^XLFDT(“1M (15@2PM,L@ 6PM)”,X)
	15353
	15354	>W X
	15355	2931031.18
	15356	Example 2
	15357	To schedul e somethin g to run e very month on the 15 th of the month at 1 1:00 p.m. and on the last day of every m onth at 8: 00 p.m., y ou would e nter the f ollowing:
	15358	Middle of the Month:
	15359	>S X=$$SCH ^XLFDT(“1M (15@11PM,L @8PM)”,293 1028)
	15360
	15361	>W X
	15362	2931031.2
	15363	End of the Month:
	15364	>S X=$$SCH ^XLFDT(“1M (15@11PM,L @8PM)”,X)
	15365
	15366	>W X
	15367	2931115.23
	15368
	15369	Example 3
	15370	To schedul e somethin g to run e very 3 mon ths on the last day of the mon th at 6:00 p.m., you would ent er the fol lowing:
	15371	Middle of the Month:
	15372	>S X=$$SCH ^XLFDT(“3M (L@6PM)”,2 930927)
	15373
	15374	>W X
	15375	2930930.18
	15376	End of the Month:
	15377	>S X=$$SCH ^XLFDT(“3M (L@6PM)”,X )
	15378
	15379	>W X
	15380	2931231.18
	15381
	15382	Example 4
	15383	The API ca n return a date that is closer to the da te the API is run if the user does not u se the for ce_future_ flag param eter and t he base_da te paramet er is set to a date in the pas t. In this example, the base_d ate parame ter is set to a date in the pa st, 11/17/ 2014 at 8: 00, and th e interval is set to find the date 2 mon ths out on the secon d Monday o f the mont h. The dat e that is returned i s the date that the API was ru n, 1/12/15 , which ha ppens to b e the seco nd Monday of the mon th and two months ou t from the base_date .
	15384	>S X=$$SCH ^XLFDT(“2M (2M@0800)” ,3141117.0 800)
	15385
	15386	>W X
	15387	3150112.08
	15388
	15389	If using t he force_f uture_flag parameter to the AP I, using t he same in terval as above, the API force s the retu rn date to be a date in the fu ture from the date t he API is run.
	15390	>S X=$$SCH ^XLFDT(“2M (2M@0800)” ,3141117.0 800,1)
	15391
	15392	>W X
	15393	3150309.08
	15394
	15395	NOTE: The base_date must be pa ssed corre ctly. The base_date parameter is compare d to the s chedule_st ring param eter in th e interval to return the corre ct output.
	15396	$$SEC^XLFD T(): Conve rt $H/VA F ileMan dat e to Secon ds
	15397	Reference Type:Suppo rted
	15398	Category:D ate Functi ons
	15399	ICR #:1010 3
	15400	Descriptio n:This ext rinsic fun ction conv erts a $H or VA File Man format ted input date to th e number o f seconds. The input date can be entered as either a VA File Man date o r a $H dat e. If ente red as a V A FileMan date, the date is fi rst conver ted to $H via the $$ FMTH^XLFDT (): Conver t VA FileM an Date to $H API.
	15401	Format:$$S EC^XLFDT(x )
	15402	Input Para meters:x:( required) VA FileMan or $H dat e.
	15403	Output:ret urns:Retur ns the $H date in se conds.
	15404
	15405	Examples
	15406	Example 1
	15407	Inputting a VA FileM an date/ti me:
	15408	>S X=$$SEC ^XLFDT(302 1118.1347)
	15409
	15410	>W X
	15411	5108536020
	15412
	15413	Example 2
	15414	Inputting a $H date:
	15415	>S X=$$SEC ^XLFDT($H)
	15416
	15417	>W X
	15418	5146022146
	15419
	15420	$$TZ^XLFDT : Time Zon e Offset ( GMT)
	15421	Reference Type:Suppo rted
	15422	Category:D ate Functi ons
	15423	ICR #:1010 3
	15424	Descriptio n:This ext rinsic fun ction retu rns the Ti me Zone of fset from Greenwich mean time (GMT) base d on a poi nter from the TIME Z ONE field (#1) in th e MAILMAN SITE PARAM ETERS file (#4.3) to the MAILM AN TIME ZO NE file (# 4.4).
	15425	The accura cy of this value is dependent on system administra tors updat ing the TI ME ZONE fi eld (#1) i n the MAIL MAN SITE P ARAMETERS file (#4.3 ) to accur ately poin t to the s ite’s corr ect time z one, inclu ding wheth er it is s tandard ti me (ST) or daylight savings ti me (DST).
	15426	Format:$$T Z^XLFDT
	15427	Input Para meters:non e.
	15428	Output:ret urns:Retur ns the Tim e Zone off set from G MT.
	15429
	15430	Example
	15431	For Pacifi c Daylight Savings T ime (PDT), the offse t from GMT is:
	15432	>S X = $$T Z^XLFDT
	15433
	15434	>W X
	15435	-0700
	15436
	15437	$$WITHIN^X LFDT(): Ch ecks Dates /Times wit hin Schedu le
	15438	Reference Type:Suppo rted
	15439	Category:D ate Functi ons
	15440	ICR #:
	15441	Descriptio n:This ext rinsic fun ction retu rns whethe r or not a date/time is within a specifi ed schedul e string.
	15442	Format:$$W ITHIN^XLFD T(schedule _string,ba se_date)
	15443	Input Para meters:sch edule_stri ng:(requir ed) Interv al to add to base_da te.
	15444	REF: For a lternate v alues, see the $$SCH ^XLFDT(): Next Sched uled Runti me API.
	15445	base_date: (required) VA FileMa n date che cked to de termine if it is wit hin the in put schedu le string.
	15446	Output:ret urns:Retur ns whether or not a date/time is within a specifie d schedule string.
	15447
	15448	Hyperbolic Trigonome tric Funct ions—XLFHY PER
	15449	The follow ing hyperb olic trigo nometric f unctions p rovide an additional set of ma thematical operation s beyond t he math fu nctions in XLFMTH.
	15450	NOTE: The optional s econd para meter in b rackets [ ] denotes the precis ion for th e function . Precisio n means th e detail o f the resu lt, in ter ms of numb er of digi ts.
	15451	$$ACOSH^XL FHYPER(): Hyperbolic Arc-cosin e
	15452	Reference Type:Suppo rted
	15453	Category:H yperbolic Trigonomet ric Functi ons
	15454	ICR #:1014 4
	15455	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc cosine, with radi ans output .
	15456	Format:$$A COSH^XLFHY PER(x[,n])
	15457	Input Para meters:x:( required) Number for which you want the hyperbolic arc cosin e.
	15458	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15459	Output:ret urns:Retur ns the hyp erbolic ar c cosine.
	15460
	15461	Example
	15462	>S X=$$ACO SH^XLFHYPE R(3,12)
	15463
	15464	>W X
	15465	1.76274717 4
	15466
	15467	$$ACOTH^XL FHYPER(): Hyperbolic Arc-cotan gent
	15468	Reference Type:Suppo rted
	15469	Category:H yperbolic Trigonomet ric Functi ons
	15470	ICR #:1014 4
	15471	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc cotange nt, with r adians out put.
	15472	Format:$$A COTH^XLFHY PER(x[,n])
	15473	Input Para meters:x:( required) Number for which you want the hyperbolic arc cotan gent.
	15474	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15475	Output:ret urns:Retur ns the hyp erbolic ar c cotangen t.
	15476
	15477	Example
	15478	>S X=$$ACO TH^XLFHYPE R(3,12)
	15479
	15480	>W X
	15481	.346573590 25
	15482
	15483	$$ACSCH^XL FHYPER(): Hyperbolic Arc-cosec ant
	15484	Reference Type:Suppo rted
	15485	Category:H yperbolic Trigonomet ric Functi ons
	15486	ICR #:1014 4
	15487	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc cosecan t, with ra dians outp ut.
	15488	Format:$$A CSCH^XLFHY PER(x[,n])
	15489	Input Para meters:x:( required) Number for which you want the hyperbolic arc cosec ant.
	15490	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15491	Output:ret urns:Retur ns the hyp erbolic ar c cosecant .
	15492
	15493	Example
	15494	>S X=$$ACS CH^XLFHYPE R(3,12)
	15495
	15496	>W X
	15497	.327450150 2
	15498
	15499	$$ASECH^XL FHYPER(): Hyperbolic Arc-secan t
	15500	Reference Type:Suppo rted
	15501	Category:H yperbolic Trigonomet ric Functi ons
	15502	ICR #:1014 4
	15503	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc secant, with radi ans output .
	15504	Format:$$A SECH^XLFHY PER(x[,n])
	15505	Input Para meters:x:( required) Number for which you want the hyperbolic arc secan t.
	15506	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15507	Output:ret urns:Retur ns the hyp erbolic ar c secant.
	15508
	15509	Example
	15510	>S X=$$ASE CH^XLFHYPE R(.3,12)
	15511
	15512	>W X
	15513	1.87382024 25
	15514
	15515	$$ASINH^XL FHYPER(): Hyperbolic Arc-sine
	15516	Reference Type:Suppo rted
	15517	Category:H yperbolic Trigonomet ric Functi ons
	15518	ICR #:1014 4
	15519	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc sine, w ith radian s output.
	15520	Format:$$S INH^XLFHYP ER(x[,n])
	15521	Input Para meters:x:( required) Number for which you want the hyperbolic arc sine.
	15522	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15523	Output:ret urns:Retur ns the hyp erbolic ar c sine.
	15524
	15525	Example
	15526	>S X=$$SIN H^XLFHYPER (3,12)
	15527
	15528	>W X
	15529	10.0178749 273
	15530
	15531	$$ATANH^XL FHYPER(): Hyperbolic Arc-tange nt
	15532	Reference Type:Suppo rted
	15533	Category:H yperbolic Trigonomet ric Functi ons
	15534	ICR #:1014 4
	15535	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc tangent , with rad ians outpu t.
	15536	Format:$$A TANH^XLFHY PER(x[,n])
	15537	Input Para meters:x:( required) Number for which you want the hyperbolic arc tange nt.
	15538	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15539	Output:ret urns:Retur ns the hyp erbolic ar c tangent.
	15540
	15541	Example
	15542	>S X=$$ATA NH^XLFHYPE R(.3,12)
	15543
	15544	>W X
	15545	.309519604 2
	15546
	15547	$$COSH ^XL FHYPER(): Hyperbolic Cosine
	15548	Reference Type:Suppo rted
	15549	Category:H yperbolic Trigonomet ric Functi ons
	15550	ICR #:1014 4
	15551	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic a rc cosine, with radi ans output .
	15552	Format:$$C OSH^XLFHYP ER(x[,n])
	15553	Input Para meters:x:( required) Number for which you want the hyperbolic cosine.
	15554	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15555	Output:ret urns:Retur ns the hyp erbolic co sine.
	15556
	15557	Example
	15558	>S X=$$COS H^XLFHYPER (3,12)
	15559
	15560	>W X
	15561	10.0676619 957
	15562
	15563	$$COTH^XLF HYPER(): H yperbolic Cotangent
	15564	Reference Type:Suppo rted
	15565	Category:H yperbolic Trigonomet ric Functi ons
	15566	ICR #:1014 4
	15567	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic c otangent, with radia ns output.
	15568	Format:$$C OTH^XLFHYP ER(x[,n])
	15569	Input Para meters:x:( required) Number for which you want the hyperbolic cotangent .
	15570	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15571	Output:ret urns:Retur ns the hyp erbolic co tangent.
	15572
	15573	Example
	15574	>S X=$$COT H^XLFHYPER (3,12)
	15575
	15576	>W X
	15577	1.00496982 332
	15578
	15579	$$CSCH^XLF HYPER(): H yperbolic Cosecant
	15580	Reference Type:Suppo rted
	15581	Category:H yperbolic Trigonomet ric Functi ons
	15582	ICR #:1014 4
	15583	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic c osecant, w ith radian s output.
	15584	Format:$$C SCH^XLFHYP ER(x[,n])
	15585	Input Para meters:x:( required) Number for which you want the hyperbolic cosecant.
	15586	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15587	Output:ret urns:Retur ns the hyp erbolic co secant.
	15588
	15589	Example
	15590	>S X=$$CSC H^XLFHYPER (3,12)
	15591
	15592	>W X
	15593	.099821569 67
	15594
	15595	$$SECH^XLF HYPER(): H yperbolic Secant
	15596	Reference Type:Suppo rted
	15597	Category:H yperbolic Trigonomet ric Functi ons
	15598	ICR #:1014 4
	15599	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic s ecant, wit h radians output.
	15600	Format:$$S ECH^XLFHYP ER(x[,n])
	15601	Input Para meters:x:( required) Number for which you want the hyperbolic secant.
	15602	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15603	Output:ret urns:Retur ns the hyp erbolic se cant.
	15604
	15605	Example
	15606	>S X=$$SEC H^XLFHYPER (3,12)
	15607
	15608	>W X
	15609	.099327927 42
	15610
	15611	$$SINH^XLF HYPER(): H yperbolic Sine
	15612	Reference Type:Suppo rted
	15613	Category:H yperbolic Trigonomet ric Functi ons
	15614	ICR #:1014 4
	15615	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic s ine, with radians ou tput.
	15616	Format:$$S INH^XLFHYP ER(x[,n])
	15617	Input Para meters:x:( required) Number for which you want the hyperbolic sine.
	15618	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15619	Output:ret urns:Retur ns the hyp erbolic si ne.
	15620
	15621	Examples
	15622	Example 1
	15623	>S X=$$SIN H^XLFHYPER (.707)
	15624
	15625	>W X
	15626	.767388542
	15627
	15628	Example 2
	15629	>S X=$$SIN H^XLFHYPER (.3,12)
	15630
	15631	>W X
	15632	.304520293 45
	15633
	15634	$$TANH^XLF HYPER(): H yperbolic Tangent
	15635	Reference Type:Suppo rted
	15636	Category:H yperbolic Trigonomet ric Functi ons
	15637	ICR #:1014 4
	15638	Descriptio n:This ext rinsic fun ction retu rns the hy perbolic t angent of x (tan x = sin x/cos x), with radians ou tput.
	15639	Format:$$T ANH^XLFHYP ER(x[,n])
	15640	Input Para meters:x:( required) Number for which you want the hyperbolic tangent.
	15641	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15642	Output:ret urns:Retur ns the hyp erbolic ta ngent.
	15643
	15644	Example
	15645	>S X=$$TAN H^XLFHYPER (3,12)
	15646
	15647	>W X
	15648	.995054753 68
	15649
	15650	Mathematic al Functio ns—XLFMTH
	15651	These call s are prov ided as an enhanceme nt to what is offere d in stand ard M. In addition, extended m ath functi ons provid e mathemat ical opera tions with adjustabl e and high er precisi on. Additi onal trigo nometric f unctions a re availab le. Angles can be sp ecified ei ther in de cimal form at or in d egrees:min utes:secon ds.
	15652	NOTE: Each optional parameter in bracket s [ ] deno tes the ma ximum and default pr ecision fo r the func tion. Prec ision mean s the deta il of the result, in terms of number of digits.
	15653	$$ABS^XLFM TH(): Abso lute Value
	15654	Reference Type:Suppo rted
	15655	Category:M ath Functi ons
	15656	ICR #:1010 5
	15657	Descriptio n:This ext rinsic fun ction retu rns the ab solute val ue of the number in x.
	15658	Format:$$A BS^XLFMTH( x)
	15659	Input Para meters:x:( required) Number for which you want the absolute v alue.
	15660	Output:ret urns:Retur ns the abs olute valu e of a num ber.
	15661
	15662	Example
	15663	>S X=$$ABS ^XLFMTH(-4 2.45)
	15664
	15665	>W X
	15666	42.45
	15667
	15668	$$ACOS^XLF MTH(): Arc -cosine (R adians)
	15669	Reference Type:Suppo rted
	15670	Category:M ath Functi ons
	15671	ICR #:1010 5
	15672	Descriptio n:This ext rinsic fun ction retu rns the ar c cosine, with radia ns output.
	15673	Format:$$A COS^XLFMTH (x[,n])
	15674	Input Para meters:x:( required) Number for which you want the arc cosine in radian s.
	15675	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15676	Output:ret urns:Retur ns the arc cosine of a number output in radians.
	15677
	15678	Example
	15679	>S X=$$ACO S^XLFMTH(. 5)
	15680
	15681	>W X
	15682	1.04719755 1
	15683
	15684	$$ACOSDEG^ XLFMTH(): Arc-cosine (Degrees)
	15685	Reference Type:Suppo rted
	15686	Category:M ath Functi ons
	15687	ICR #:1010 5
	15688	Descriptio n:This ext rinsic fun ction retu rns the ar c cosine, with degre es output.
	15689	Format:$$A COSDEG^XLF MTH(x[,n])
	15690	Input Para meters:x:( required) Number for which you want the arc cosine in degree s.
	15691	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15692	Output:ret urns:Retur ns the arc cosine of a number output in degrees.
	15693
	15694	Example
	15695	>S X=$$ACO SDEG^XLFMT H(.5)
	15696
	15697	>W X
	15698	60
	15699
	15700	$$ACOT^XLF MTH(): Arc -cotangent (Radians)
	15701	Reference Type:Suppo rted
	15702	Category:M ath Functi ons
	15703	ICR #:1010 5
	15704	Descriptio n:This ext rinsic fun ction retu rns the ar c cotangen t, with ra dians outp ut.
	15705	Format:$$A COT^XLFMTH (x[,n])
	15706	Input Para meters:x:( required) Number for which you want the arc cotang ent in rad ians.
	15707	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15708	Output:ret urns:Retur ns the arc cotangent of a numb er output in radians .
	15709
	15710	Example
	15711	>S X=$$ACO T^XLFMTH(. 5)
	15712
	15713	>W X
	15714	1.10714871 8
	15715
	15716	$$ACOTDEG^ XLFMTH(): Arc-cotang ent (Degre es)
	15717	Reference Type:Suppo rted
	15718	Category:M ath Functi ons
	15719	ICR #:1010 5
	15720	Descriptio n:This ext rinsic fun ction retu rns the ar c cotangen t, with de grees outp ut.
	15721	Format:$$A COTDEG^XLF MTH(x[,n])
	15722	Input Para meters:x:( required) Number for which you want the arc cotang ent in deg rees.
	15723	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15724	Output:ret urns:Retur ns the arc cotangent of a numb er output in degrees .
	15725
	15726	Example
	15727	>S X=$$ACO TDEG^XLFMT H(.5)
	15728
	15729	>W X
	15730	63.4349488 2
	15731
	15732	$$ACSC^XLF MTH(): Arc -cosecant (Radians)
	15733	Reference Type:Suppo rted
	15734	Category:M ath Functi ons
	15735	ICR #:1010 5
	15736	Descriptio n:This ext rinsic fun ction retu rns the ar c cosecant , with rad ians outpu t.
	15737	Format:$$A CSC^XLFMTH (x[,n])
	15738	Input Para meters:x:( required) Number for which you want the arc coseca nt in radi ans.
	15739	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15740	Output:ret urns:Retur ns the arc cosecant of a numbe r output i n radians.
	15741
	15742	Example
	15743	>S X=$$ACS C^XLFMTH(1 .5)
	15744
	15745	>W X
	15746	.729727656
	15747
	15748	$$ACSCDEG^ XLFMTH(): Arc-coseca nt (Degree s)
	15749	Reference Type:Suppo rted
	15750	Category:M ath Functi ons
	15751	ICR #:1010 5
	15752	Descriptio n:This ext rinsic fun ction retu rns the ar c cosecant , with deg rees outpu t.
	15753	Format:$$A CSCDEG^XLF MTH(x[,n])
	15754	Input Para meters:x:( required) Number for which you want the arc coseca nt in degr ees.
	15755	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15756	Output:ret urns:Retur ns the arc cosecant of a numbe r output i n degrees.
	15757
	15758	Example
	15759	>S X=$$ACS CDEG^XLFMT H(1.5)
	15760
	15761	>W X
	15762	41.8103149
	15763
	15764	$$ASEC^XLF MTH(): Arc -secant (R adians)
	15765	Reference Type:Suppo rted
	15766	Category:M ath Functi ons
	15767	ICR #:1010 5
	15768	Descriptio n:This ext rinsic fun ction retu rns the ar c secant, with radia ns output.
	15769	Format:$$A SEC^XLFMTH (x[,n])
	15770	Input Para meters:x:( required) Number for which you want the arc secant in radian s.
	15771	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15772	Output:ret urns:Retur ns the arc secant of a number output in radians.
	15773
	15774	Example
	15775	>S X=$$ASE C^XLFMTH(1 .5)
	15776
	15777	>W X
	15778	.841068671
	15779
	15780	$$ASECDEG^ XLFMTH(): Arc-secant (Degrees)
	15781	Reference Type:Suppo rted
	15782	Category:M ath Functi ons
	15783	ICR #:1010 5
	15784	Descriptio n:This ext rinsic fun ction retu rns the ar c secant, with degre es output.
	15785	Format:$$A SECDEG^XLF MTH(x[,n])
	15786	Input Para meters:x:( required) Number for which you want the arc secant in degree s.
	15787	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15788	Output:ret urns:Retur ns the arc secant of a number output in degrees.
	15789
	15790	Example
	15791	>S X=$$ASE CDEG^XLFMT H(1.5)
	15792
	15793	>W X
	15794	48.1896851
	15795
	15796	$$ASIN^XLF MTH(): Arc -sine (Rad ians)
	15797	Reference Type:Suppo rted
	15798	Category:M ath Functi ons
	15799	ICR #:1010 5
	15800	Descriptio n:This ext rinsic fun ction retu rns the ar c sine, wi th radians output.
	15801	Format:$$A SIN^XLFMTH (x[,n])
	15802	Input Para meters:x:( required) Number for which you want the arc sine i n radians.
	15803	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15804	Output:ret urns:Retur ns the arc sine of a number ou tput in ra dians.
	15805
	15806	Example
	15807	>S X=$$ASI N^XLFMTH(. 5)
	15808
	15809	>W X
	15810	.523598776
	15811
	15812	$$ASINDEG^ XLFMTH(): Arc-sine ( Degrees)
	15813	Reference Type:Suppo rted
	15814	Category:M ath Functi ons
	15815	ICR #:1010 5
	15816	Descriptio n:This ext rinsic fun ction retu rns the ar c sine, wi th degrees output.
	15817	Format:$$A SINDEG^XLF MTH(x[,n])
	15818	Input Para meters:x:( required) Number for which you want the arc sine i n degrees.
	15819	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15820	Output:ret urns:Retur ns the arc sine of a number ou tput in de grees.
	15821
	15822	Example
	15823	>S X=$$ASI NDEG^XLFMT H(.5)
	15824
	15825	>W X
	15826	30
	15827
	15828	$$ATAN^XLF MTH(): Arc -tangent ( Radians)
	15829	Reference Type:Suppo rted
	15830	Category:M ath Functi ons
	15831	ICR #:1010 5
	15832	Descriptio n:This ext rinsic fun ction retu rns the ar c tangent, with radi ans output .
	15833	Format:$$A TAN^XLFMTH (x[,n])
	15834	Input Para meters:x:( required) Number for which you want the arc tangen t in radia ns.
	15835	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15836	Output:ret urns:Retur ns the arc tangent o f a number output in radians.
	15837
	15838	Example
	15839	>S X=$$ATA N^XLFMTH(. 5)
	15840
	15841	>W X
	15842	.463647609
	15843
	15844	$$ATANDEG^ XLFMTH(): Arc-tangen t (Degrees )
	15845	Reference Type:Suppo rted
	15846	Category:M ath Functi ons
	15847	ICR #:1010 5
	15848	Descriptio n:This ext rinsic fun ction retu rns the ar c tangent, with degr ees output .
	15849	Format:$$A TANDEG^XLF MTH(x[,n])
	15850	Input Para meters:x:( required) Number for which you want the arc tangen t in degre es.
	15851	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15852	Output:ret urns:Retur ns the arc tangent o f a number output in degrees.
	15853
	15854	Example
	15855	>S X=$$ATA NDEG^XLFMT H(.5)
	15856
	15857	>W X
	15858	26.5650511 8
	15859
	15860	$$COS^XLFM TH(): Cosi ne (Radian s)
	15861	Reference Type:Suppo rted
	15862	Category:M ath Functi ons
	15863	ICR #:1010 5
	15864	Descriptio n:This ext rinsic fun ction retu rns the co sine, with radians i nput.
	15865	Format:$$C OS^XLFMTH( x[,n])
	15866	Input Para meters:x:( required) Radians in put number for which you want the cosine .
	15867	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15868	Output:ret urns:Retur ns the cos ine of rad ians input number.
	15869
	15870	Example
	15871	>S X=$$COS ^XLFMTH(1. 5)
	15872
	15873	>W X
	15874	.070737202
	15875
	15876	$$COSDEG^X LFMTH(): C osine (Deg rees)
	15877	Reference Type:Suppo rted
	15878	Category:M ath Functi ons
	15879	ICR #:1010 5
	15880	Descriptio n:This ext rinsic fun ction retu rns the co sine, with degrees i nput.
	15881	Format:$$C OSDEG^XLFM TH(x[,n])
	15882	Input Para meters:x:( required) Degrees in put number for which you want the cosine .
	15883	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15884	Output:ret urns:Retur ns the cos ine of deg rees input number.
	15885
	15886	Example
	15887	>S X=$$COS DEG^XLFMTH (45)
	15888
	15889	>W X
	15890	.707106781
	15891
	15892	$$COT^XLFM TH(): Cota ngent (Rad ians)
	15893	Reference Type:Suppo rted
	15894	Category:M ath Functi ons
	15895	ICR #:1010 5
	15896	Descriptio n:This ext rinsic fun ction retu rns the co tangent, w ith radian s input.
	15897	Format:$$C OT^XLFMTH( x[,n])
	15898	Input Para meters:x:( required) Radians in put number for which you want the cotang ent.
	15899	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15900	Output:ret urns:Retur ns the cot angent of radians in put number .
	15901
	15902	Example
	15903	>S X=$$COT ^XLFMTH(1. 5)
	15904
	15905	>W X
	15906	.070914844
	15907
	15908	$$COTDEG^X LFMTH(): C otangent ( Degrees)
	15909	Reference Type:Suppo rted
	15910	Category:M ath Functi ons
	15911	ICR #:1010 5
	15912	Descriptio n:This ext rinsic fun ction retu rns the co tangent, w ith degree s input.
	15913	Format:$$C OTDEG^XLFM TH(x[,n])
	15914	Input Para meters:x:( required) Degrees in put number for which you want the cotang ent.
	15915	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15916	Output:ret urns:Retur ns the cot angent of degrees in put number .
	15917
	15918	Example
	15919	>S X=$$COT DEG^XLFMTH (45)
	15920
	15921	>W X
	15922	1
	15923
	15924	$$CSC^XLFM TH(): Cose cant (Radi ans)
	15925	Reference Type:Suppo rted
	15926	Category:M ath Functi ons
	15927	ICR #:1010 5
	15928	Descriptio n:This ext rinsic fun ction retu rns the co secant, wi th radians input.
	15929	Format:$$C SC^XLFMTH( x[,n])
	15930	Input Para meters:x:( required) Radians in put number for which you want the coseca nt.
	15931	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15932	Output:ret urns:Retur ns the cos ecant of r adians inp ut number.
	15933
	15934	Example
	15935	>S X=$$CSC ^XLFMTH(1. 5)
	15936
	15937	>W X
	15938	1.00251130 4
	15939
	15940	$$CSCDEG^X LFMTH(): C osecant (D egrees)
	15941	Reference Type:Suppo rted
	15942	Category:M ath Functi ons
	15943	ICR #:1010 5
	15944	Descriptio n:This ext rinsic fun ction retu rns the co secant, wi th degrees input.
	15945	Format:$$C SCDEG^XLFM TH(x[,n])
	15946	Input Para meters:x:( required) Degrees in put number for which you want the coseca nt.
	15947	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15948	Output:ret urns:Retur ns the cos ecant of d egrees inp ut number.
	15949
	15950	Example
	15951	>S X=$$CSC DEG^XLFMTH (45)
	15952
	15953	>W X
	15954	1.41421356 2
	15955
	15956	$$DECDMS^X LFMTH(): C onvert Dec imals to D egrees:Min utes:Secon ds
	15957	Reference Type:Suppo rted
	15958	Category:M ath Functi ons
	15959	ICR #:1010 5
	15960	Descriptio n:This ext rinsic fun ction conv erts a num ber from d ecimal to degrees:mi nutes:seco nds.
	15961	Format:$$D ECDMS^XLFM TH(x[,n])
	15962	Input Para meters:x:( required) Decimal nu mber to be converted to degree :minutes:s econd.
	15963	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15964	Output:ret urns:Retur ns the con verted dec imal input number to degrees:m inutes:sec onds.
	15965
	15966	Example
	15967	>S X=$$DEC DMS^XLFMTH (30.7)
	15968
	15969	>W X
	15970	30:42:0
	15971
	15972	$$DMSDEC^X LFMTH(): C onvert Deg rees:Minut es:Seconds to Decima l
	15973	Reference Type:Suppo rted
	15974	Category:M ath Functi ons
	15975	ICR #:1010 5
	15976	Descriptio n:This ext rinsic fun ction conv erts a num ber from d egrees:min utes:secon ds to a de cimal.
	15977	Format:$$D MSDEC^XLFM TH(x[,n])
	15978	Input Para meters:x:( required) Degrees:mi nutes:seco nds input number to be convert ed to deci mal.
	15979	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15980	Output:ret urns:Retur ns the con verted deg rees:minut es:seconds input num ber to dec imal.
	15981
	15982	Example
	15983	>S X=$$DMS DEC^XLFMTH (“30:42:0” )
	15984
	15985	>W X
	15986	30.7
	15987
	15988	$$DTR^XLFM TH(): Conv ert Degree s to Radia ns
	15989	Reference Type:Suppo rted
	15990	Category:M ath Functi ons
	15991	ICR #:1010 5
	15992	Descriptio n:This ext rinsic fun ction conv erts degre es to radi ans.
	15993	Format:$$D TR^XLFMTH( x[,n])
	15994	Input Para meters:x:( required) Degrees in put number to be con verted to radians.
	15995	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	15996	Output:ret urns:Retur ns the con verted deg rees input number to radians.
	15997
	15998	Example
	15999	>S X=$$DTR ^XLFMTH(45 )
	16000
	16001	>W X
	16002	.785398163 4
	16003
	16004	$$E^XLFMTH (): e—Natu ral Logari thm
	16005	Reference Type:Suppo rted
	16006	Category:M ath Functi ons
	16007	ICR #:1010 5
	16008	Descriptio n:This ext rinsic fun ction retu rns e (nat ural logar ithm).
	16009	Format:$$E ^XLFMTH([n ])
	16010	Input Para meters:n:( optional) The precis ion for th e function . Precisio n means th e detail o f the resu lt, in ter ms of numb er of digi ts.
	16011	Output:ret urns:Retur ns e, natu ral logari thm.
	16012
	16013	Example
	16014	>S X=$$E^X LFMTH(12)
	16015
	16016	>W X
	16017	2.71828182 846
	16018
	16019	$$EXP^XLFM TH(): e—Na tural Loga rithm to t he Nth Pow er
	16020	Reference Type:Suppo rted
	16021	Category:M ath Functi ons
	16022	ICR #:1010 5
	16023	Descriptio n:This ext rinsic fun ction retu rns e (nat ural logar ithm) to t he x power (exponent ).
	16024	Format:$$E XP^XLFMTH( x[,n])
	16025	Input Para meters:x:( required) The power to which y ou want e raised.
	16026	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16027	Output:ret urns:Retur ns the val ue of e to the speci fied power .
	16028
	16029	Example
	16030	>S X=$$EXP ^XLFMTH(1. 532)
	16031
	16032	>W X
	16033	4.62742241 85
	16034
	16035	$$LN^XLFMT H(): Natur al Log (Ba se e)
	16036	Reference Type:Suppo rted
	16037	Category:M ath Functi ons
	16038	ICR #:1010 5
	16039	Descriptio n:This ext rinsic fun ction retu rns the na tural log of x (Base e).
	16040	Format:$$L N^XLFMTH(x [,n])
	16041	Input Para meters:x:( required) Number for which you want the natural lo g.
	16042	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16043	Output:ret urns:Retur ns the nat ural log o f a number .
	16044
	16045	Example
	16046	>S X=$$LN^ XLFMTH(4.6 27426)
	16047
	16048	>W X
	16049	1.53200077 4
	16050
	16051	$$LOG^XLFM TH(): Loga rithm (Bas e 10)
	16052	Reference Type:Suppo rted
	16053	Category:M ath Functi ons
	16054	ICR #:1010 5
	16055	Descriptio n:This ext rinsic fun ction retu rns the lo garithm (B ase 10) of x.
	16056	Format:$$L OG^XLFMTH( x[,n])
	16057	Input Para meters:x:( required) Number for which you want the logarithm.
	16058	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16059	Output:ret urns:Retur ns the log arithm (Ba se 10) of input numb er.
	16060
	16061	Example
	16062	>S X=$$LOG ^XLFMTH(3. 1415)
	16063
	16064	>W X
	16065	.497137064 1
	16066
	16067	$$MAX^XLFM TH(): Maxi mum of Two Numbers
	16068	Reference Type:Suppo rted
	16069	Category:M ath Functi ons
	16070	ICR #:1010 5
	16071	Descriptio n:This ext rinsic fun ction retu rns the ma ximum valu e by compa ring the n umber in x with the number in y.
	16072	Format:$$M AX^XLFMTH( x,y)
	16073	Input Para meters:x:( required) First numb er to comp are with s econd numb er in y to determine which is higher in value.
	16074	y:(require d) Second number to compare wi th first n umber in x to determ ine which is higher in value.
	16075	Output:ret urns:Retur ns the hig hest numbe r.
	16076
	16077	Example
	16078	>S X=$$MAX ^XLFMTH(53 ,24)
	16079
	16080	>W X
	16081	53
	16082
	16083	$$MIN^XLFM TH(): Mini mum of Two Numbers
	16084	Reference Type:Suppo rted
	16085	Category:M ath Functi ons
	16086	ICR #:1010 5
	16087	Descriptio n:This ext rinsic fun ction retu rns the mi nimum valu e by compa ring the n umber in x with the number in y.
	16088	Format:$$M IN^XLFMTH( x,y)
	16089	Input Para meters:x:( required) First numb er to comp are with s econd numb er in y to determine which is lower in v alue.
	16090	y:(require d) Second number to compare wi th first n umber in x to determ ine which is lower i n value.
	16091	Output:ret urns:Retur ns the low est number .
	16092
	16093	Example
	16094	>S X=$$MIN ^XLFMTH(53 ,24)
	16095
	16096	>W X
	16097	24
	16098
	16099	$$PI^XLFMT H(): PI
	16100	Reference Type:Suppo rted
	16101	Category:M ath Functi ons
	16102	ICR #:1010 5
	16103	Descriptio n:This ext rinsic fun ction retu rns pi.
	16104	Format:$$P I^XLFMTH([ n])
	16105	Input Para meters:n:( optional) The precis ion for th e function . Precisio n means th e detail o f the resu lt, in ter ms of numb er of digi ts.
	16106	Output:ret urns:Retur ns pi.
	16107
	16108	Example
	16109	>S X=$$PI^ XLFMTH(12)
	16110
	16111	>W X
	16112	3.14159265 359
	16113
	16114	$$PWR^XLFM TH(): X to the Y Pow er
	16115	Reference Type:Suppo rted
	16116	Category:M ath Functi ons
	16117	ICR #:1010 5
	16118	Descriptio n:This ext rinsic fun ction retu rns x to t he y power . This fun ction make s use of L N and EXP.
	16119	Format:$$P WR^XLFMTH( x,y[,n])
	16120	Input Para meters:x:( required) Number for which you want the exponent v alue.
	16121	y:(require d) The exp onent to w hich the i nput numbe r (x) shou ld be rais ed.
	16122	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16123	Output:ret urns:Retur ns the exp onent valu e.
	16124
	16125	Example
	16126	>S X=$$PWR ^XLFMTH(3. 2,1.5)
	16127
	16128	>W X
	16129	5.72433402 24
	16130
	16131	$$RTD^XLFM TH(): Conv ert Radian s to Degre es
	16132	Reference Type:Suppo rted
	16133	Category:M ath Functi ons
	16134	ICR #:1010 5
	16135	Descriptio n:This ext rinsic fun ction conv erts radia ns to degr ees.
	16136	Format:$$R TD^XLFMTH( x[,n])
	16137	Input Para meters:x:( required) Radians in put number to be con verted to degrees.
	16138	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16139	Output:ret urns:Retur ns the con verted rad ians input number to degrees.
	16140
	16141	Example
	16142	>S X=$$RTD ^XLFMTH(1. 5,12)
	16143
	16144	>W X
	16145	85.9436692 696
	16146
	16147	$$SD^XLFMT H(): Stand ard Deviat ion
	16148	Reference Type:Suppo rted
	16149	Category:M ath Functi ons
	16150	ICR #:1010 5
	16151	Descriptio n:This ext rinsic fun ction retu rns the st andard dev iation. St andard dev iation is defined as :
	16152	“A measure of variab ility equa l to the s quare root of the ar ithmetic a verage of the square s of the d eviations from the m ean in a f requency d istributio n.”
	16153	Format:$$S D^XLFMTH(% s1,%s2,%n)
	16154	Input Para meters:%s1 :(required ) Sum.
	16155	%s2:(requi red) Sum o f squares.
	16156	%n:(requir ed) Count.
	16157	Output:ret urns:Retur ns the sta ndard devi ation.
	16158
	16159	Example
	16160	>S X=$$SD^ XLFMTH(5,2 5,2)
	16161
	16162	>W X
	16163	3.53553390 593
	16164
	16165	$$SEC^XLFM TH(): Seca nt (Radian s)
	16166	Reference Type:Suppo rted
	16167	Category:M ath Functi ons
	16168	ICR #:1010 5
	16169	Descriptio n:This ext rinsic fun ction retu rns the se cant of a number, wi th radians input.
	16170	Format:$$S EC^XLFMTH( x[,n])
	16171	Input Para meters:x:( required) Number in radians fo r which yo u want the secant.
	16172	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16173	Output:ret urns:Retur ns the sec ant of rad ians input number.
	16174
	16175	Example
	16176	>S X=$$SEC ^XLFMTH(1. 5)
	16177
	16178	>W X
	16179	14.1368329
	16180
	16181	$$SECDEG^X LFMTH(): S ecant (Deg rees)
	16182	Reference Type:Suppo rted
	16183	Category:M ath Functi ons
	16184	ICR #:1010 5
	16185	Descriptio n:This ext rinsic fun ction retu rns the se cant of a number, wi th degrees input.
	16186	Format:$$S ECDEG^XLFM TH(x[,n])
	16187	Input Para meters:x:( required) Number in degrees fo r which yo u want the secant.
	16188	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16189	Output:ret urns:Retur ns the sec ant of deg rees input number.
	16190
	16191	Example
	16192	>S X=$$SEC DEG^XLFMTH (45)
	16193
	16194	>W X
	16195	1.41421356 2
	16196
	16197	$$SIN^XLFM TH(): Sine (Radians)
	16198	Reference Type:Suppo rted
	16199	Category:M ath Functi ons
	16200	ICR #:1010 5
	16201	Descriptio n:This ext rinsic fun ction retu rns the si ne of a nu mber, with radians i nput.
	16202	Format:$$S IN^XLFMTH( x[,n])
	16203	Input Para meters:x:( required) Number in radians fo r which yo u want the sine.
	16204	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16205	Output:ret urns:Retur ns the sin e of radia ns input n umber.
	16206
	16207	Example
	16208	>S X=$$SIN ^XLFMTH(.7 853982)
	16209
	16210	>W X
	16211	.707106807
	16212
	16213	$$SINDEG^X LFMTH(): S ine (Degre es)
	16214	Reference Type:Suppo rted
	16215	Category:M ath Functi ons
	16216	ICR #:1010 5
	16217	Descriptio n:This ext rinsic fun ction retu rns the si ne of a nu mber, with degrees i nput.
	16218	Format:$$S INDEG^XLFM TH(x[,n])
	16219	Input Para meters:x:( required) Number in degrees fo r which yo u want the sine.
	16220	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16221	Output:ret urns:Retur ns the sin e of degre es input n umber.
	16222
	16223	Example
	16224	>S X=$$SIN DEG^XLFMTH (45)
	16225
	16226	>W X
	16227	.707106781
	16228
	16229	$$SQRT^XLF MTH(): Squ are Root
	16230	Reference Type:Suppo rted
	16231	Category:M ath Functi ons
	16232	ICR #:1010 5
	16233	Descriptio n:This ext rinsic fun ction retu rns the sq uare root of a numbe r.
	16234	Format:$$S QRT^XLFMTH (x[,n])
	16235	Input Para meters:x:( required) Number for which you want the square roo t.
	16236	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16237	Output:ret urns:Retur ns the squ are root o f input nu mber.
	16238
	16239	Example
	16240	>S X=$$SQR T^XLFMTH(1 53)
	16241
	16242	>W X
	16243	12.3693168 769
	16244
	16245	$$TAN^XLFM TH(): Tang ent (Radia ns)
	16246	Reference Type:Suppo rted
	16247	Category:M ath Functi ons
	16248	ICR #:1010 5
	16249	Descriptio n:This ext rinsic fun ction retu rns the ta ngent of a number (t an x = sin x/cos x), with radi ans input.
	16250	Format:$$T AN^XLFMTH( x[,n])
	16251	Input Para meters:x:( required) Number in radians fo r which yo u want the tangent.
	16252	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16253	Output:ret urns:Retur ns the tan gent of ra dians inpu t number.
	16254
	16255	Example
	16256	>S X=$$TAN ^XLFMTH(.7 853982)
	16257
	16258	>W X
	16259	1.00000007 3
	16260
	16261	$$TANDEG^X LFMTH(): T angent (De grees)
	16262	Reference Type:Suppo rted
	16263	Category:M ath Functi ons
	16264	ICR #:1010 5
	16265	Descriptio n:This ext rinsic fun ction retu rns the ta ngent of a number, w ith degree s input.
	16266	Format:$$T ANDEG^XLFM TH(x[,n])
	16267	Input Para meters:x:( required) Number in degrees fo r which yo u want the tangent.
	16268	n:(optiona l) The pre cision for the funct ion. Preci sion means the detai l of the r esult, in terms of n umber of d igits.
	16269	Output:ret urns:Retur ns the tan gent of de grees inpu t number.
	16270
	16271	Example
	16272	>S X=$$TAN DEG^XLFMTH (45)
	16273
	16274	>W X
	16275	1
	16276
	16277	Measuremen t Function s—XLFMSMT
	16278	This routi ne contain s APIs to allow conv ersion bet ween U.S. (English) and Metric units.
	16279	$$BSA^XLFM SMT(): Bod y Surface Area Measu rement
	16280	Reference Type:Suppo rted
	16281	Category:M easurement Functions
	16282	ICR #:3175 & 10143
	16283	Descriptio n:This ext rinsic fun ction retu rns the bo dy surface area.
	16284	Format:$$B SA^XLFMSMT (ht,wt)
	16285	Input Para meters:ht: (required) Height in centimete rs.
	16286	wt:(requir ed) Weight in kilogr ams.
	16287	Output:ret urns:Retur ns the bod y surface area measu rement.
	16288
	16289	Examples
	16290	Example 1
	16291	>S X=$$BSA ^XLFMSMT(1 75,86)
	16292
	16293	>W X
	16294	2.02
	16295
	16296	Example 2
	16297	>S X=$$BSA ^XLFMSMT($ $LENGTH^XL FMSMT(69,“ IN”,“CM”), $$WEIGHT^X LFMSMT(180 ,“LB”,“KG” ))
	16298
	16299	>W X
	16300	1.98
	16301
	16302	$$LENGTH^X LFMSMT(): Convert Le ngth Measu rement
	16303	Reference Type:Suppo rted
	16304	Category:M easurement Functions
	16305	ICR #:3175 & 10143
	16306	Descriptio n:This ext rinsic fun ction conv erts U.S. length to Metric len gth and vi ce versa. It returns the equiv alent valu e with uni ts.
	16307	Format:$$L ENGTH^XLFM SMT(value, from,to)
	16308	Input Para meters:val ue:(requir ed) A posi tive numer ic value.
	16309	from:(requ ired) Unit of measur e of the v alue input parameter (see Tabl e 41).
	16310	to:(requir ed) Unit o f measure to which t he value i nput param eter is co nverted (s ee Table 4 1).
	16311	Valid unit s in eithe r uppercas e or lower case are:
	16312	Table 41: $$LENGTH^X LFMSMT API —Valid uni ts
	16313	Metric
	16314	US
	16315	km—kilomet ers
	16316	mi—miles
	16317	m—meters
	16318	yd—yards
	16319	cm—centime ters
	16320	ft—feet
	16321	mm—millime ters
	16322	in—inches
	16323
	16324	Output:ret urns:Retur ns the len gth measur ement.
	16325
	16326	Examples
	16327	Example 1
	16328	Converting U.S. leng th to Metr ic length:
	16329	>S X=$$LEN GTH^XLFMSM T(12,“IN”, “CM”)
	16330
	16331	>W X
	16332	30.48 CM
	16333
	16334	Example 2
	16335	Converting Metric le ngth to U. S. length:
	16336	>S X=$$LEN GTH^XLFMSM T(30.48,“c m”,“in”)
	16337
	16338	>W X
	16339	12 IN
	16340
	16341	$$TEMP^XLF MSMT(): Co nvert Temp erature Me asurement
	16342	Reference Type:Suppo rted
	16343	Category:M easurement Functions
	16344	ICR #:3175 & 10143
	16345	Descriptio n:This ext rinsic fun ction conv erts U.S. temperatur e to Metri c temperat ure and vi ce versa. It returns the equiv alent valu e with uni ts.
	16346	Format:$$T EMP^XLFMSM T(value,fr om,to)
	16347	Input Para meters:val ue:(requir ed) A posi tive numer ic value.
	16348	from:(requ ired) Unit of measur e of the v alue input parameter (see Tabl e 42).
	16349	to:(requir ed) Unit o f measure to which t he value i nput param eter is co nverted (s ee Table 4 2).
	16350	Valid unit s in eithe r uppercas e or lower case are:
	16351	Table 42: $$TEMP^XLF MSMT API—V alid units
	16352	Metric
	16353	US
	16354	C—Celsius
	16355	F—Fahrenhe it
	16356
	16357	Output:ret urns:Retur ns the tem perature m easurement .
	16358
	16359	Examples
	16360	Example 1
	16361	Converting Fahrenhei t to Celsi us:
	16362	>S X=$$TEM P^XLFMSMT( 72,“F”,“C” )
	16363
	16364	>W X
	16365	22.222 C
	16366
	16367	Example 2
	16368	Converting Celsius t o Fahrenhe it:
	16369	>S X=$$TEM P^XLFMSMT( 0,“c”,“f”)
	16370
	16371	>W X
	16372	32 F
	16373
	16374	$$VOLUME^X LFMSMT(): Convert Vo lume Measu rement
	16375	Reference Type:Suppo rted
	16376	Category:M easurement Functions
	16377	ICR #:3175 & 10143
	16378	Descriptio n:This ext rinsic fun ction conv erts U.S. volume to Metric vol ume and vi ce versa. Converts m illiliters to cubic inches or quarts or ounces. It returns t he equival ent value with units .
	16379	Format:$$V OLUME^XLFM SMT(value, from,to)
	16380	Input Para meters:val ue:(requir ed) A posi tive numer ic value.
	16381	from:(requ ired) Unit of measur e of the v alue input parameter (see Tabl e 43).
	16382	to:(requir ed) Unit o f measure to which t he value i nput param eter is co nverted (s ee Table 4 3).
	16383	Valid unit s in eithe r uppercas e or lower case are:
	16384	Table 43: $$VOLUME^X LFMSMT API —Valid uni ts
	16385	Metric
	16386	US
	16387	kl— kiloli ter
	16388	cf—cubic f eet
	16389	hl—hectoli ter
	16390	ci—cubic i nch
	16391	dal—dekali ter
	16392	gal—gallon
	16393	l—liters
	16394	qt—quart
	16395	dl—decilit er
	16396	pt—pint
	16397	cl—centili ter
	16398	c—cup
	16399	ml—millili ter
	16400	oz— ounce
	16401
	16402	Output:ret urns:Retur ns the vol ume measur ement.
	16403
	16404	Examples
	16405	Example 1
	16406	Converting U.S. volu me to Metr ic volume:
	16407	>S X=$$VOL UME^XLFMSM T(12,“CF”, “ML”)
	16408
	16409	>W X
	16410	339800.832 ML
	16411
	16412	Example 2
	16413	Converting Metric vo lume to U. S. volume:
	16414	>S X=$$VOL UME^XLFMSM T(339800.8 32,“ml”,“c f”)
	16415
	16416	>W X
	16417	11.998 CF
	16418
	16419	$$WEIGHT^X LFMSMT(): Convert We ight Measu rement
	16420	Reference Type:Suppo rted
	16421	Category:M easurement Functions
	16422	ICR #:3175 & 10143
	16423	Descriptio n:This ext rinsic fun ction conv erts U.S. weights to proximate Metric we ights and vice versa . It retur ns the equ ivalent va lue with u nits.
	16424	Format:$$W EIGHT^XLFM SMT(value, from,to)
	16425	Input Para meters:val ue:(requir ed) A posi tive numer ic value.
	16426	from:(requ ired) Unit of measur e of the v alue input parameter (see Tabl e 44).
	16427	to:(requir ed) Unit o f measure to which t he value i nput param eter is co nverted (s ee Table 4 4).
	16428	Valid unit s in eithe r uppercas e or lower case are:
	16429	Table 44: $$WEIGHT^X LFMSMT API —Valid uni ts
	16430	Metric
	16431	US
	16432	t—metric t ons
	16433	tn— tons
	16434	kg—kilogra ms
	16435	lb—pounds
	16436	g—grams
	16437	oz—ounces
	16438	mg—milligr am
	16439	gr—grain
	16440
	16441	Output:ret urns:Retur ns the wei ght measur ement.
	16442
	16443	Examples
	16444	Example 1
	16445	Converting U.S. weig ht to Metr ic weight:
	16446	>S X=$$WEI GHT^XLFMSM T(12,“LB”, “G”)
	16447
	16448	>W X
	16449	5448 G
	16450
	16451	Example 2
	16452	Converting Metric we ight to U. S. weight:
	16453	>S X=$$WEI GHT^XLFMSM T(5448,“g” ,“lb”)
	16454
	16455	>W X
	16456	12.011 LB
	16457
	16458	String Fun ctions—XLF STR
	16459	These func tions are provided t o help pro cess strin gs.
	16460	$$CJ^XLFST R(): Cente r Justify String
	16461	Reference Type:Suppo rted
	16462	Category:S tring Func tions
	16463	ICR #:1010 4
	16464	Descriptio n:This ext rinsic fun ction retu rns a cent er justifi ed charact er string.
	16465	Format:$$C J^XLFSTR(s ,i[,p])
	16466	Input Para meters:s:( required) Character string.
	16467	i:(require d) Field s ize. If th is second parameter contains a trailing “T”, this extrinsic function r eturns the output tr uncated to the field size spec ified.
	16468	p:(optiona l) Pad cha racter.
	16469	Output:ret urns:Retur ns the Cen ter justif ied string .
	16470
	16471	Examples
	16472	Example 1
	16473	>W “[“,$$C J^XLFSTR(“ SUE”,10),“ ]”
	16474	[ SUE ]
	16475
	16476	Example 2
	16477	>W “[“,$$C J^XLFSTR(“ SUE”,10,“- ”),“]”
	16478	[---SUE--- -]
	16479
	16480	Example 3
	16481	>W $$CJ^XL FSTR(“1234 56789”,5)
	16482	123456789
	16483
	16484	Example 4
	16485	>W $$CJ^XL FSTR(12345 6789,“5T”)
	16486	12345
	16487
	16488	$$INVERT^X LFSTR(): I nvert Stri ng
	16489	Reference Type:Suppo rted
	16490	Category:S tring Func tions
	16491	ICR #:1010 4
	16492	Descriptio n:This ext rinsic fun ction retu rns an inv erted stri ng. It inv erts the o rder of th e characte rs in a st ring.
	16493	Format:$$I NVERT^XLFS TR(x)
	16494	Input Para meters:x:( required) Character string.
	16495	Output:ret urns:Retur ns the inv erted stri ng.
	16496
	16497	Example
	16498	>S X=$$INV ERT^XLFSTR (“ABC”)
	16499
	16500	>W X
	16501	CBA
	16502
	16503	$$LJ^XLFST R(): Left Justify St ring
	16504	Reference Type:Suppo rted
	16505	Category:S tring Func tions
	16506	ICR #:1010 4
	16507	Descriptio n:This ext rinsic fun ction retu rns a left justified character string.
	16508	Format:$$L J^XLFSTR(s ,i[,p])
	16509	Input Para meters:s:( required) Character string.
	16510	i:(require d) Field s ize. If th is second parameter contains a trailing “T”, this extrinsic function r eturns the output tr uncated to the field size spec ified.
	16511	p:(optiona l) Pad cha racter.
	16512	Output:ret urns:Retur ns the lef t justifie d string.
	16513
	16514	Examples
	16515	Example 1
	16516	>W “[“,$$L J^XLFSTR(“ TOM”,10),“ ]”
	16517	[TOM ]
	16518
	16519	Example 2
	16520	>W “[“,$$L J^XLFSTR(“ TOM”,10,“- ”),“]”
	16521	[TOM------ -]
	16522
	16523	Example 3
	16524	>W $$LJ^XL FSTR(“1234 56789”,5)
	16525	123456789
	16526
	16527	Example 4
	16528	>W $$LJ^XL FSTR(12345 6789,“5T”)
	16529	12345
	16530
	16531	$$LOW^XLFS TR(): Conv ert String to Lowerc ase
	16532	Reference Type:Suppo rted
	16533	Category:S tring Func tions
	16534	ICR #:1010 4
	16535	Descriptio n:This ext rinsic fun ction retu rns an inp ut string converted to all low ercase.
	16536	Format:$$L OW^XLFSTR( x)
	16537	Input Para meters:x:( required) Character string.
	16538	Output:ret urns:Retur ns the inp ut string converted to all low ercase.
	16539
	16540	Example
	16541	>S X=$$LOW ^XLFSTR(“J USTICE”)
	16542
	16543	>W X
	16544	justice
	16545
	16546	$$REPEAT^X LFSTR(): R epeat Stri ng
	16547	Reference Type:Suppo rted
	16548	Category:S tring Func tions
	16549	ICR #:1010 4
	16550	Descriptio n:This ext rinsic fun ction retu rns a stri ng that re peats the value of x for y num ber of tim es.
	16551	Format:$$R EPEAT^XLFS TR(x[,y])
	16552	Input Para meters:x:( required) Character string to be repeate d.
	16553	y:(optiona l) Number of times t o repeat t he string in x.
	16554	Output:ret urns:Retur ns the rep eated stri ng.
	16555
	16556	Examples
	16557	Example 1
	16558	>S X=$$REP EAT^XLFSTR (“-”,10)
	16559
	16560	>W X
	16561	----------
	16562
	16563	Example 2
	16564	>S X=$$REP EAT^XLFSTR (“blue wat er “,5)
	16565
	16566	>W X
	16567	blue water blue wate r blue wat er blue wa ter blue w ater
	16568
	16569	$$REPLACE^ XLFSTR(): Replace St rings
	16570	Reference Type:Suppo rted
	16571	Category:S tring Func tions
	16572	ICR #:1010 4
	16573	Descriptio n:This ext rinsic fun ction uses a multi-c haracter $ Translate to return a string w ith the sp ecified st ring repla ced.
	16574	Format:$$R EPLACE^XLF STR(in,.sp ec)
	16575	Input Para meters:in: (required) Input str ing.
	16576	.spec:(req uired) An array pass ed by refe rence.
	16577	Output:ret urns:Retur ns the rep laced stri ng.
	16578
	16579	Examples
	16580	Example 1
	16581	>SET spec( “aa”)=“a”, spec(“pqr” )=“alabama ”
	16582	>S X=$$REP LACE^XLFST R(“aaaaaaq raaaaaaa”, .spec)
	16583
	16584	>W X
	16585	aaaaalabam aaaaa
	16586
	16587	Example 2
	16588	>SET spec( “F”)=“VA F ile”,spec( “M”)=“Man”
	16589	>S X=$$REP LACE^XLFST R(“FM”,.sp ec)
	16590
	16591	>W X
	16592	VA FileMan
	16593
	16594	$$RJ^XLFST R(): Right Justify S tring
	16595	Reference Type:Suppo rted
	16596	Category:S tring Func tions
	16597	ICR #:1010 4
	16598	Descriptio n:This ext rinsic fun ction retu rns a righ t justifie d characte r string.
	16599	Format:$$R J^XLFSTR(s ,i[,p])
	16600	Input Para meters:s:( required) Character string.
	16601	i:(require d) Field s ize. If th is second parameter contains a trailing “T”, this extrinsic function r eturns the output tr uncated to the field size spec ified.
	16602	p:(optiona l) Pad cha racter.
	16603	Output:ret urns:Retur ns the rig ht justifi ed string.
	16604
	16605	Examples
	16606	Example 1
	16607	>W “[“,$$R J^XLFSTR(“ TOM”,10),“ ]”
	16608	[ TO M]
	16609
	16610	Example 2
	16611	>W “[“,$$R J^XLFSTR(“ TOM”,10,“- ”),“]”
	16612	[-------TO M]
	16613
	16614	Example 3
	16615	>W $$RJ^XL FSTR(“1234 56789”,5)
	16616	123456789
	16617
	16618	Example 4
	16619	>W $$RJ^XL FSTR(12345 6789,“5T”)
	16620	12345
	16621
	16622	$$SENTENCE ^XLFSTR(): Convert S tring to S entence Ca se
	16623	Reference Type:Suppo rted
	16624	Category:S tring Func tions
	16625	ICR #:1010 4
	16626	Descriptio n:Released with Kern el patch X U8.0400, this extr insic func tion retur ns an inpu t string c onverted t o Sentence case. The initial c haracter o f each sen tence in t he input s tring is c apitalized and the r emaining c haracters in that se ntence are returned as all low ercase. Th e first ch aracter of the strin g begins a sentence. Subsequen t sentence s are iden tified as beginning after a pe riod (.), exclamatio n point (! ), or ques tion mark (?).
	16627	Format:$$S ENTENCE^XL FSTR(x)
	16628	Input Para meters:x:( required) Character string.
	16629	Output:ret urns:Retur ns the str ing conver ted to Sen tence case format.
	16630
	16631	Example
	16632	>S X=$$SEN TENCE^XLFS TR(“HELLO WORLD!!! T HIS IS A C APITALIZED SENTENCE. this is n ot.”)
	16633
	16634	>W X
	16635	Hello worl d!!! This is a capit alized sen tence. Thi s is not.
	16636
	16637	$$STRIP^XL FSTR(): St rip a Stri ng
	16638	Reference Type:Suppo rted
	16639	Category:S tring Func tions
	16640	ICR #:1010 4
	16641	Descriptio n:This ext rinsic fun ction retu rns a stri ng strippe d of all i nstances o f a specif ied charac ter.
	16642	Format:$$S TRIP^XLFST R(x,y)
	16643	Input Para meters:x:( required) Character string.
	16644	y:(require d) The cha racter to strip out of the str ing.
	16645	Output:ret urns:Retur ns the str ing stripp ed of spec ified char acter.
	16646
	16647	Examples
	16648	Example 1
	16649	>S X=$$STR IP^XLFSTR( “hello”,“e ”)
	16650
	16651	>W X
	16652	hllo
	16653
	16654	Example 2
	16655	>S X=$$STR IP^XLFSTR( “Mississip pi”,“i”)
	16656
	16657	>W X
	16658	Msssspp
	16659
	16660	$$TITLE^XL FSTR(): Co nvert Stri ng to Titl e Case
	16661	Reference Type:Suppo rted
	16662	Category:S tring Func tions
	16663	ICR #:1010 4
	16664	Descriptio n:Released with Kern el patch X U8.0400, this extr insic func tion retur ns an inpu t string c onverted t o Title ca se. The in itial lett er of the first bloc k of chara cters (i.e ., word) i n the inpu t string i s capitali zed and th e remainin g characte rs of that first wor d are retu rned as al l lowercas e. Also, t he initial letter of any subse quent word in the in put string is capita lized and the remain ing charac ters in th at word ar e returned as all lo wercase. A word is i dentified when it is preceded by at leas t one spac e, except for the fi rst word i n the stri ng.
	16665	Format:$$T ITLE^XLFST R(x)
	16666	Input Para meters:x:( required) Character string.
	16667	Output:ret urns:Retur ns the str ing conver ted to Tit le case fo rmat.
	16668
	16669	Example
	16670	>S X=$$TIT LE^XLFSTR( “HELLO WOR LD!!! THIS IS A titl e-form SEN TENCE. so is this.”)
	16671
	16672	>W X
	16673	Hello Worl d!!! This Is A Title -form Sent ence. So I s This.
	16674
	16675	$$TRIM^XLF STR(): Tri m String
	16676	Reference Type:Suppo rted
	16677	Category:S tring Func tions
	16678	ICR #:1010 4
	16679	Descriptio n:This ext rinsic fun ction trim s spaces o r other sp ecified ch aracters f rom the le ft, right, or both e nds of an input stri ng.
	16680	Format:$$T RIM^XLFSTR (s[,f][,c] )
	16681	Input Para meters:s:( required) Character string.
	16682	f:(optiona l) This fl ag can hav e the foll owing valu e:
	16683	“LR” (defa ult)—Trim characters from both ends of t he string.
	16684	“L”—Trim c haracters from the l eft/beginn ing of the string.
	16685	“R”—Trim c haracters from the r ight/end o f the stri ng.
	16686	c:(optiona l) Set thi s paramete r to the c haracter t o trim fro m the inpu t string. This param eter defau lts to a s pace.
	16687	Output:ret urns:Retur ns the tri mmed strin g.
	16688
	16689	Examples
	16690	Example 1
	16691	In this ex ample, we are trimmi ng the spa ces from b oth the le ft and rig ht end of the string (the brac kets are a dded to mo re clearly display t he trimmed string):
	16692	>S X=“[“_$ $TRIM^XLFS TR(“ A B C “)_”]”
	16693
	16694	>W X
	16695	[A B C]
	16696
	16697	The second input par ameter def aults to “ LR” and th e third in put parame ter defaul ts to spac es.
	16698	Example 2
	16699	In this ex ample, we are trimmi ng the sla shes from both the l eft and ri ght end of the strin g (the bra ckets are added to m ore clearl y display the trimme d string):
	16700	>S X=“[“_$ $TRIM^XLFS TR(“//A B C//”,,“/”) _“]”
	16701
	16702	>W X
	16703	[A B C]
	16704
	16705	The second input par ameter def aults to “ LR.”
	16706	Example 3
	16707	In this ex ample, we are trimmi ng the sla shes from the left e nd of the string (th e brackets are added to more c learly dis play the t rimmed str ing):
	16708	>S X=“[“_$ $TRIM^XLFS TR(“//A B C//”,“L”,“ /”)_“]”
	16709
	16710	>W X
	16711	[A B C//]
	16712
	16713	Example 4
	16714	In this ex ample, we are trimmi ng the sla shes from the right end of the string (t he bracket s are adde d to more clearly di splay the trimmed st ring):
	16715	>S X=“[”_$ $TRIM^XLFS TR(“//A B C//”,“r”,“ /”)_“]”
	16716
	16717	>W X
	16718	[//A B C]
	16719
	16720	$$UP^XLFST R(): Conve rt String to Upperca se
	16721	Reference Type:Suppo rted
	16722	Category:S tring Func tions
	16723	ICR #:1010 4
	16724	Descriptio n:This ext rinsic fun ction retu rns an inp ut string converted to all upp ercase.
	16725	Format:$$U P^XLFSTR(x )
	16726	Input Para meters:x:( required) Character string.
	16727	Output:ret urns:Retur ns the str ing conver ted to all uppercase .
	16728
	16729	Example
	16730	>S X=$$UP^ XLFSTR(“fr eedom”)
	16731
	16732	>W X
	16733	FREEDOM
	16734
	16735	Utility Fu nctions—XL FUTL
	16736	These func tions are provided t o help wit h a variet y of tasks .
	16737	$$BASE^XLF UTL(): Con vert Betwe en Two Bas es
	16738	Reference Type:Suppo rted
	16739	Category:U tility Fun ctions
	16740	ICR #:2622
	16741	Descriptio n:This ext rinsic fun ction conv erts a num ber from o ne base to another. The base m ust be bet ween 2 and 16, both from and t o paramete rs.
	16742	Format:$$B ASE^XLFUT L(n,from,t o)
	16743	Input Para meters:n:( required) Number to convert.
	16744	from:(requ ired) Base of number being con verted.
	16745	to:(requir ed) Base t o which th e number i s to be co nverted.
	16746	Output:ret urns:Retur ns the con verted num ber from o ne base to another.
	16747
	16748	Examples
	16749	Example 1
	16750	>S X=$$BAS E^XLFUTL(1 111,2,16)
	16751
	16752	>W X
	16753	F
	16754
	16755	Example 2
	16756	>S X=$$BAS E^XLFUTL(1 5,10,16)
	16757
	16758	>W X
	16759	F
	16760
	16761	Example 3
	16762	>S X=$$BAS E^XLFUTL(“ FF”,16,10)
	16763
	16764	>W X
	16765	255
	16766
	16767	$$CCD^XLFU TL(): Appe nd Check D igit
	16768	Reference Type:Suppo rted
	16769	Category:U tility Fun ctions
	16770	ICR #:2622
	16771	Descriptio n:This ext rinsic fun ction retu rns a numb er appende d with a c omputed ch eck digit. To check if the ori ginal numb er corresp onds with the append ed check d igit, use the $$VCD^ XLFUTL(): Verify Int egrity API .
	16772	Format:$$C CD^XLFUTL( x)
	16773	Input Para meters:x:( required) Integer fo r which th e check di git is com puted.
	16774	REF: See “ The Taylor Report” i n Computer world maga zine, 1975 , for the algorithm.
	16775	Output:ret urns:Retur ns the num ber with a ppended ch eck digit.
	16776
	16777	Examples
	16778	Example 1
	16779	>S X=$$CCD ^XLFUTL(99 889)
	16780
	16781	>W X
	16782	998898
	16783
	16784	Example 2
	16785	>S X=$$CCD ^XLFUTL(76 54321)
	16786
	16787	>W X
	16788	76543214
	16789
	16790	$$CNV^XLFU TL(): Conv ert Base 1 0 to Anoth er Base
	16791	Reference Type:Suppo rted
	16792	Category:U tility Fun ctions
	16793	ICR #:2622
	16794	Descriptio n:This ext rinsic fun ction conv erts a num ber from B ase 10 to another ba se, which must be be tween 2 an d 16.
	16795	Format:$$C NV^XLFUTL( n,base)
	16796	Input Para meters:n:( required) Base 10 nu mber to co nvert.
	16797	base:(requ ired) The base to wh ich the nu mber is to be conver ted.
	16798	Output:ret urns:Retur ns the con verted num ber to spe cified bas e.
	16799
	16800	Examples
	16801	Example 1
	16802	>S X=$$CNV ^XLFUTL(15 ,2)
	16803
	16804	>W X
	16805	1111
	16806
	16807	Example 2
	16808	>S X=$$CNV ^XLFUTL(25 5,2)
	16809
	16810	>W X
	16811	11111111
	16812
	16813	Example 3
	16814	>S X=$$CNV ^XLFUTL(25 5,8)
	16815
	16816	>W X
	16817	377
	16818
	16819	$$DEC^XLFU TL(): Conv ert Anothe r Base to Base 10
	16820	Reference Type:Suppo rted
	16821	Category:U tility Fun ctions
	16822	ICR #:2622
	16823	Descriptio n:This ext rinsic fun ction conv erts a num ber from a specified base, whi ch must be between 2 and 16, t o Base 10.
	16824	Format:$$D EC^XLFUTL( n,base)
	16825	Input Para meters:n:( required) Number to convert.
	16826	base:(requ ired) Base of number being con verted.
	16827	Output:ret urns:Retur ns the con verted num ber in Bas e 10.
	16828
	16829	Example
	16830	>S X=$$DEC ^XLFUTL(“F F”,16)
	16831
	16832	>W X
	16833	255
	16834
	16835	$$VCD^XLFU TL(): Veri fy Integri ty
	16836	Reference Type:Suppo rted
	16837	Category:U tility Fun ctions
	16838	ICR #:2622
	16839	Descriptio n:This ext rinsic fun ction veri fies the i ntegrity o f a number with an a ppended ch eck digit. The check digit mus t be appen ded by the $$CCD^XLF UTL(): App end Check Digit API.
	16840	Format:$$V CD^XLFUTL( number)
	16841	Input Para meters:num ber:(requi red) Numbe r to verif y, includi ng appende d check di git.
	16842	Output:ret urns:Retur ns:
	16843	1—Number c orresponds to check digit.
	16844	0—Number d oes not co rrespond t o check di git.
	16845
	16846	Examples
	16847	Example 1
	16848	>S X=$$VCD ^XLFUTL(76 543214)
	16849
	16850	>W X
	16851	1
	16852
	16853	Example 2
	16854	Transposin g “32” to “23”:
	16855	>S X=$$VCD ^XLFUTL(76 542314)
	16856
	16857	>W X
	16858	0
	16859
	16860
	16861	IP Address Functions —XLFIPV
	16862	These call s are prov ided to st andardize the storag e and proc essing of Internet P rotocol (I P) address es. Storin g addresse s in a sta ndardized format sim plifies VA FileMan s earch and sort funct ions. It a lso simpli fies the p rocessing of address es in M ro utines. Wh en VistA i s used in an IPv4/IP v6 dual-st ack enviro nment, som e performa nce degrad ation can occur due to the nee d to try m ultiple IP address c ombination s when mak ing networ k connecti ons. There fore, it i s importan t to simpl ify and st andardize this proce ss wheneve r possible .
	16863	$$CONVERT^ XLFIPV():C onvert any IP Addres s to Stand ardized IP Address F ormat
	16864	Reference Type:Suppo rted
	16865	Category:I P Address Functions
	16866	ICR #:5844
	16867	Descriptio n:This ext rinsic fun ction conv erts an In ternet Pro tocol (IP) address ( either IPv 4 or IPv6) into an I P address in a stand ardized fo rmat, depe nding upon the syste m settings :
	16868	IPv4—$$FOR CEIP4^XLFI PV(): Conv ert any IP Address t o IPv4 API .
	16869	IPv6—$$FOR CEIP6^XLFI PV(): Conv ert any IP Address t o IPv6 API .
	16870	Format:$$C ONVERT^XLF IPV(ip)
	16871	Input Para meters:ip: (required) IPv4 or I Pv6 addres s (string; in quotes ) to be co nverted.
	16872	Output:ret urns:Retur ns:
	16873	An IPv4 ad dress if I Pv6 is dis abled on t he system.
	16874	An IPv6 ad dress if I Pv6 is ena bled on th e system.
	16875	An IPv4 or IPv6 null address i f the inpu t cannot b e converte d.
	16876
	16877	Examples
	16878	Example 1 (IPv6 Enab led)
	16879	>S X=$$CON VERT^XLFIP V(“10.126. 3.1”)
	16880
	16881	>W X
	16882	0000:0000: 0000:0000: 0000:FFFF: 0A7E:0301
	16883
	16884	Example 2 (IPv6 Disa bled)
	16885	>S X=$$CON VERT^XLFIP V(“10.126. 3.1”)
	16886
	16887	>W X
	16888	10.126.3.1
	16889
	16890	Example 3 (IPv6 Enab led)
	16891	>S X=$$CON VERT^XLFIP V(“2001:db 8::8a2e:37 0:7334”)
	16892
	16893	>W X
	16894	2001:0DB8: 0000:0000: 0000:8A2E: 0370:7334
	16895
	16896	Example 4 (IPv6 Disa bled)
	16897	>S X=$$CON VERT^XLFIP V(“2001:db 8::8a2e:37 0:7334”)
	16898
	16899	>W X
	16900	0.0.0.0
	16901
	16902	$$FORCEIP4 ^XLFIPV(): Convert a ny IP Addr ess to IPv 4
	16903	Reference Type:Suppo rted
	16904	Category:I P Address Functions
	16905	ICR #:5844
	16906	Descriptio n:This ext rinsic fun ction conv erts an IP address ( either IPv 4 or IPv6) into an I Pv4 addres s in a sta ndardized format con sisting of four deci mal number s, each in the range 0 to 255. For examp le:
	16907	001.99.001 .9
	16908	Format:$$F ORCEIP4^XL FIPV(ip)
	16909	Input Para meters:ip: (required) IPv4 or I Pv6 addres s (string; in quotes ) to be co nverted.
	16910	Output:ret urns:Retur ns:
	16911	An IPv4 ad dress in “ nnn.nnn.nn n.nnn” not ation if t he input a ddress is valid and has an IPv 4 equivale nt.
	16912	The null a ddress “0. 0.0.0” if the input address is invalid.
	16913	The null a ddress “0. 0.0.0” if an IPv6 ad dress is i nput that does not h ave an IPv 4 equivale nt.
	16914
	16915	Examples
	16916	Example 1
	16917	>S X=$$FOR CEIP4^XLFI PV(“10.126 .3.1”)
	16918
	16919	>W X
	16920	10.126.3.1
	16921
	16922	Example 2
	16923	>S X=$$FOR CEIP4^XLFI PV(“10.999 .3.1”)
	16924
	16925	>W X
	16926	0.0.0.0
	16927
	16928	Example 3
	16929	>S X=$$FOR CEIP4^XLFI PV(“2001:d b8::8a2e:3 70:7334”)
	16930
	16931	>W X
	16932	0.0.0.0
	16933
	16934	Example 4
	16935	>S X=$$FOR CEIP4^XLFI PV(“::ffff :10.126.3. 1”)
	16936
	16937	>W X
	16938	10.126.3.1
	16939
	16940	Example 5
	16941	>S X=$$FOR CEIP4^XLFI PV(“::ffff :c000:2eb” )
	16942
	16943	>W X
	16944	192.0.2.23 5
	16945
	16946	$$FORCEIP6 ^XLFIPV(): Convert a ny IP Addr ess to IPv 6
	16947	Reference Type:Suppo rted
	16948	Category:I P Address Functions
	16949	ICR #:5844
	16950	Descriptio n:This ext rinsic fun ction conv erts an IP address ( either IPv 4 or IPv6) into an I Pv6 addres s in a sta ndardized format con sisting of eight gro ups of hex adecimal n umbers sep arated by colons. Fo r example:
	16951	2001:0DB8: 85A3:0042: 0000:8A2E: 0370:7334
	16952	Format:$$F ORCEIP6^XL FIPV(ip)
	16953	Input Para meters:ip: (required) IPv4 or I Pv6 addres s (string; in quotes ) to be co nverted.
	16954	Output:ret urns:Retur ns:
	16955	An IPv6 ad dress in “ hhhh:hhhh: hhhh:hhhh: hhhh:hhhh: hhhh:hhhh” notation if the inp ut address is valid and has an IPv6 equi valent.
	16956	The null a ddress “00 00:0000:00 00:0000:00 00:0000:00 00:0000” i f the inpu t address is invalid .
	16957
	16958	Examples
	16959	Example 1
	16960	>S X=$$FOR CEIP6^XLFI PV(“10.126 .3.1”)
	16961
	16962	>W X
	16963	0000:0000: 0000:0000: 0000:FFFF: 0A7E:0301
	16964
	16965	Example 2
	16966	>S X=$$FOR CEIP6^XLFI PV(“10.999 .3.1”)
	16967
	16968	>W X
	16969	0000:0000: 0000:0000: 0000:0000: 0000:0000
	16970
	16971	Example 3
	16972	>S X=$$FOR CEIP6^XLFI PV(“2001:d b8::8a2e:3 70:7334”)
	16973
	16974	>W X
	16975	2001:0DB8: 0000:0000: 0000:8A2E: 0370:7334
	16976	Example 4
	16977	>S X=$$FOR CEIP6^XLFI PV(“::ffff :10.126.3. 1”)
	16978
	16979	>W X
	16980	0000:0000: 0000:0000: 0000:FFFF: 0A7E:0301
	16981
	16982	Example 5
	16983	>S X=$$FOR CEIP6^XLFI PV(“127.0. 0.1”)
	16984
	16985	>W X
	16986	0000:0000: 0000:0000: 0000:0000: 0000:0001
	16987
	16988	$$VALIDATE ^XLFIPV(): Validate IP Address Format
	16989	Reference Type:Suppo rted
	16990	Category:I P Address Functions
	16991	ICR #:5844
	16992	Descriptio n:This ext rinsic fun ction vali dates the format of an IP addr ess (eithe r IPv4 or IPv6).
	16993	Format:$$V ALIDATE^XL FIPV(ip)
	16994	Input Para meters:ip: (required) IPv4 or I Pv6 addres s (string) to be val idated.
	16995	Output:ret urns:Retur ns:
	16996	1—If the I P address is in a va lid format .
	16997	0—If the f ormat is i nvalid or null input .
	16998
	16999	Examples
	17000	Example 1
	17001	>S X=$$VAL IDATE^XLFI PV(10.126. 3.1)
	17002
	17003	>W X
	17004	1
	17005
	17006	Example 2
	17007	>S X=$$VAL IDATE^XLFI PV(10.999. 3.1)
	17008
	17009	>W X
	17010	0
	17011
	17012	Example 3
	17013	>S X=$$VAL IDATE^XLFI PV(2001:db 8::8a2e:37 0:7334)
	17014
	17015	>W X
	17016	1
	17017
	17018	Example 4
	17019	>S X=$$VAL IDATE^XLFI PV(2001:db 8::8g2h:37 0:7334)
	17020
	17021	>W X
	17022	0
	17023
	17024	$$VERSION^ XLFIPV: Sh ow System Settings f or IPv6
	17025	Reference Type:Suppo rted
	17026	Category:I P Address Functions
	17027	ICR #:5844
	17028	Descriptio n:This ext rinsic fun ction dete rmines the system se ttings for IPv6.
	17029	Format:$$V ERSION^XLF IPV
	17030	Input Para meters:non e.
	17031	Output:ret urns:Retur ns:
	17032	1—If IPv6 is enabled .
	17033	0—If IPv6 is disable d.
	17034
	17035	Examples
	17036	Example 1 (IPv6 Enab led)
	17037	>S X=$$VER SION^XLFIP V
	17038
	17039	>W X
	17040	1
	17041
	17042	Example 2 (IPv6 Disa bled)
	17043	>S X=$$VER SION^XLFIP V
	17044
	17045	>W X
	17046	0
	17047
	17048	JSON Conve rsion Func tions—XLFJ SON
	17049	These call s are prov ided to st andardize the conver sion of a global or array to t he JSON fo rmat, and JSON to a global or array form at. They also inclu de functio ns to prep are string s for the JSON conve rsion proc ess, by es caping (ma king JSON complient) or unesca ping (maki ng code co mplient) s trings.DEC ODE^XLFJSO N(): Conve rt a JSON object int o a closed array ref erence.
	17050	Reference Type:Suppo rted
	17051	Category:J SON Conver sion Funct ions
	17052	ICR #:6682
	17053	Descriptio n:This sub routine co nverts a J SON object into a cl osed array reference .
	17054	Format:DEC ODE^XLFJSO N (XUJSON, XUROOT,XUE RR)
	17055	Input Para meters:XUJ SON:(requi red) A str ing or arr ay contain ing a seri alized JSO N object.
	17056	Output:XUR OOT:(requi red) A clo sed array reference for M repr esentation of the ob ject.
	17057	XUERR:(opt ional) Thi s contains error mes sages. If not defin ed, defaul ts to ^TMP (“XLFJERR” ,$J).
	17058
	17059	Examples
	17060	Example 1
	17061	>S INJSON( 1)="{""men u"":{""id" ":""file"" ,""popup"" :{""menuit em"":[{""v alue
	17062	"": ""New" ",""onclic k"":""Crea teNewDoc() ""},"
	17063
	17064	>S INJSON( 2)="{""val ue"": ""Op en"",""onc lick"": "" OpenDoc()" "},{""valu e"":
	17065	""Close"", ""onclick" ": ""Close Doc()""}]} ,"
	17066
	17067	>S INJSON( 3)="""valu e"":""File ""}}"
	17068
	17069	>D DECODE^ XLFJSON("I NJSON","OU TJSON","ER RORS")
	17070
	17071	>ZW OUTJSO N
	17072	OUTJSON("m enu","id") ="file"
	17073	OUTJSON("m enu","popu p","menuit em",1,"onc lick")="Cr eateNewDoc ()"
	17074	OUTJSON("m enu","popu p","menuit em",1,"val ue")="New"
	17075	OUTJSON("m enu","popu p","menuit em",2,"onc lick")="Op enDoc()"
	17076	OUTJSON("m enu","popu p","menuit em",2,"val ue")="Open "
	17077	OUTJSON("m enu","popu p","menuit em",3,"onc lick")="Cl oseDoc()"
	17078	OUTJSON("m enu","popu p","menuit em",3,"val ue")="Clos e"
	17079	OUTJSON("m enu","valu e")="File"
	17080
	17081	ENCODE^XLF JSON(): Co nvert clos ed array o r global r eference t o a JSON o bject.
	17082	Reference Type:Suppo rted
	17083	Category:J SON Conver sion Funct ions
	17084	ICR #:6682
	17085	Descriptio n:This sub routine co nverts a c losed arra y or globa l referenc e to a JSO N object.
	17086	Format:ENC ODE^XLFJSO N(XUROOT,X UJSON,XUER R)
	17087	Input Para meters:XUR OOT:(requi red) A clo sed array reference for M repr esentation of the ob ject.
	17088	Output:XUJ SON:(requi red) A str ing or arr ay contain ing a seri alized JSO N object.
	17089	XUERR:(opt ional) Thi s contains error mes sages. If not defin ed, defaul ts to ^TMP (“XLFJERR” ,$J).
	17090
	17091	Examples
	17092	Example 1
	17093	>S Y("menu ","id")="f ile"
	17094
	17095	>S Y("menu ","popup", "menuitem" ,1,"onclic k")="Creat eNewDoc()"
	17096
	17097	>S Y("menu ","popup", "menuitem" ,1,"value" )="New"
	17098
	17099	>S Y("menu ","popup", "menuitem" ,2,"onclic k")="OpenD oc()"
	17100
	17101	>S Y("menu ","popup", "menuitem" ,2,"value" )="Open"
	17102
	17103	>S Y("menu ","popup", "menuitem" ,3,"onclic k")="Close Doc()"
	17104
	17105	>S Y("menu ","popup", "menuitem" ,3,"value" )="Close"
	17106
	17107	>S Y("menu ","value") ="File"
	17108
	17109	>D ENCODE^ XLFJSON("Y ","OUTJSON ","ERRORS" )
	17110
	17111	W OUTJSON( 1)
	17112	{"menu":{" id":"file" ,"popup":{ "menuitem" :[{"onclic k":"Create NewDoc()", "value":"N
	17113	ew"},{"onc lick":"Ope nDoc()","v alue":"Ope n"},{"oncl ick":"Clos eDoc()","v alue":"Clo
	17114	se"}]},"va lue":"File "}}
	17115
	17116	$$ESC^XLFJ SON(): Esc ape string to JSON.
	17117	Reference Type:Suppo rted
	17118	Category:J SON Conver sion Funct ions
	17119	ICR #:6682
	17120	Descriptio n:This fun ction retu rns an esc aped strin g in a JSO N format.
	17121	Format:$$E SC^XLFJSON (X)
	17122	Input Para meters:X:( required) A string t o be escap ed to a JS ON format.
	17123	Output:A J SON escape d string.
	17124
	17125	Examples
	17126	Example 1
	17127	>W $$ESC^X LFJSON("\o ne\two\thr ee\")
	17128	\\one\\two \\three\\
	17129
	17130	$$UES^XLFJ SON(): Une scape JSON to a stri ng.
	17131	Reference Type:Suppo rted
	17132	Category:J SON Conver sion Funct ions
	17133	ICR #:6682
	17134	Descriptio n:This fun ction retu rns a unes caped stri ng from a JSON forma t.
	17135	Format:$$U ES^XLFJSON (X)
	17136	Input Para meters:X:( required) A JSON esc aped strin g to be un escaped.
	17137	Output:A u nescaped s tring repr esentation of the es caped JSON input str ing.
	17138
	17139	Examples
	17140	Example 1
	17141	>W $$UES^X LFJSON("\\ one\\two\\ three\\")
	17142	\one\two\t hree\
	17143
	17144
	17145
	17146	XML Parser (VistA): Developer Tools
	17147	Overview
	17148	The VistA Extensible Markup La nguage (XM L) Parser is a full- featured, validating XML parse r written in the M p rogramming language and design ed to inte rface with the VistA suite of M-based ap plications . It is no t a standa lone produ ct. Rather , it acts as a serve r applicat ion that c an provide XML parsi ng capabil ities to a ny client applicatio n that sub scribes to the appli cation pro grammer in terface (A PI) specif ication de tailed in this docum ent.
	17149	The VistA XML Parser employs t wo very di fferent AP I implemen tations:
	17150	Event-driv en Interfa ce
	17151	World Wide Web Conso rtium Docu ment Objec t Model Sp ecificatio n
	17152	The choice of which API to emp loy is in part depen dent on th e needs of the appli cation dev eloper. Th e event-dr iven inter face requi res the cl ient appli cation to process th e document in a stri ctly top-d own manner . In contr ast, the i n-memory m odel provi des the ab ility to m ove freely throughou t the docu ment and h as the add ed advanta ge of ensu ring that the docume nt is well formed an d valid be fore any i nformation is return ed to the client app lication.
	17153	The VistA XML Parser employs a n Entity C atalog to allow stor age of ext ernal enti ties such as documen t type def initions. The Entity Catalog i s a VA Fil eMan-compa tible data base and c an be mani pulated us ing the us ual VA Fil eMan tools .
	17154	Event-driv en Interfa ce
	17155	The event- driven int erface is modeled af ter the wi dely used Simple API for XML ( SAX) inter face speci fication. In this im plementati on, a clie nt applica tion provi des a spec ial handle r for each parsing e vent of in terest. Wh en the cli ent invoke s the pars er, it con veys not o nly the do cument to be parsed, but also the entry points for each of i ts event h andlers. A s the pars er progres ses throug h the docu ment, it i nvokes the client’s handlers f or each pa rsing even t for whic h a handle r has been registere d.
	17156	World Wide Web Conso rtium Docu ment Objec t Model Sp ecificatio n
	17157	This API i mplementat ion is bas ed on the World Wide Web Conso rtium (W3C s) Documen t Object M odel (DOM) specific ation. Thi s API, whi ch is actu ally built on top of the event -driven in terface, f irst const ructs an i n-memory m odel of th e fully pa rsed and v alidated d ocument. I t then pro vides meth ods to nav igate thro ugh and ex tract info rmation fr om the par sed docume nt.
	17158	This API i s actually layered o n top of t he event-d riven API. In other words, it is actuall y a client of the ev ent-driven API that in turn ac ts as a se rver to an other clie nt applica tion.
	17159	The docume nt image i s represen ted intern ally as a tree with each node in the tre e represen ting an el ement inst ance. Att ributes (n ames and v alues), no n-markup t ext, and c omment tex t may be a ssociated with any g iven node. For examp le, in Fig ure 152 th e XML docu ment on th e left is represente d by the t ree struct ure on the right.
	17160	Figure 152 : XML Docu ment (left )—Tree str ucture Dia gram (righ t)
	17161
	17162
	17163	Entity Cat alog
	17164	The XML EN TITY CATAL OG file (# 950) is us ed to stor e external entities and their associated public id entifiers. When the XML parser encounter s an exter nal entity reference with a pu blic ident ifier, it first look s for that public id entifier i n the enti ty catalog . If it fi nds the en tity, it r etrieves i ts value. Otherwise, it attemp ts to retr ieve the e ntity valu e using th e system i dentifier. The probl em with us ing system identifie rs is that they ofte n identify resources that may have been relocated since the document w as authore d. (This i s analogou s to the p roblem wit h broken l inks in HT ML documen ts.) Using public id entifiers and an ent ity catalo g allows o ne to buil d a collec tion of co mmonly use d and read ily access ible exter nal entiti es (e.g., external d ocument ty pe definit ions).
	17165	The XML EN TITY CATAL OG file (# 950) is a VA FileMan -compatibl e file tha t is very simple in structure as shown i n Table 45 .
	17166	Table 45: XML ENTITY CATALOG f ile (#950) —Stores ex ternal ent ities and assoc publ ic identif iers
	17167	Field #
	17168	Field Name
	17169	Datatype
	17170	Descriptio n
	17171	.01
	17172	ID
	17173	Free text( 1-250)
	17174	The public identifie r associat ed with th is entity.
	17175	1
	17176	VALUE
	17177	Word Proce ssing
	17178	The text a ssociated with the e ntity.
	17179
	17180	Term Defin itions and XML Parse r Concept
	17181	To underst and the te rms used i n this sec tion and t he concept of the op eration of an XML Pa rser, plea se review the W3C Ar chitecture Domain we bsite, Ext ensible Ma rkup Langu age (XML) page at: h ttp://www. w3.org/XML /
	17182	The Toolki t VistA XM L Parser A pplication Programmi ng Interfa ces (APIs) have been developed to assist you in cr eating an XML docume nt.
	17183	Integratio n Control Registrati on #3561 d efines the various c allable en try points in the MX MLDOM rout ine. These APIs are based on t he W3C’s D ocument Ob ject Model (DOM) spe cification . It first builds an “in-memor y” image o f the full y parsed a nd validat ed documen t and then provides a set of m ethods to permit str uctured tr aversal of the docum ent and ex traction o f its cont ents. This API is ac tually lay ered on to p of the e vent-drive n API. In other word s, it is a ctually a client of the event- driven API that in t urn acts a s a server to anothe r client a pplication .
	17184	REF: The V istA Exten sible Mark up Languag e (XML) Pa rser techn ical and u ser docume ntation ca n be found on the VA Software Document L ibrary (VD L) located at: http: //www. DOMAIN /vdl/appli cation.asp ?appid=137
	17185	Known Issu es
	17186	The follow ing are kn own issues in this v ersion of the XML pa rser. Some of these are due to certain l imitations of the M programmin g language .
	17187	Unsupporte d Characte r Encoding s
	17188	Unlike lan guages lik e Java tha t have mul tiple char acter enco ding suppo rt built-i n, M does not recogn ize charac ter encodi ngs that d o not inco rporate th e printabl e ASCII ch aracter su bset. Thus , 16-bit c haracter e ncodings (e.g., Uni code) are not suppor ted. Fortu nately, a large numb er of 8-bi t characte r encoding s do incor porate the printable ASCII cha racter sub set and ca n be parse d. Because of this l imitation, the VistA XML Parse r rejects any docume nts with u nsupported character encodings .
	17189	Retrieval of Externa l Entities Using Non -Standard File Acces s Protocol s
	17190	The curren t version of the Vis tA XML Par ser does n ot support retrieval of extern al entitie s using th e HTTP or FTP protoc ols (or fo r that mat ter, any p rotocols o ther than the standa rd file ac cess proto cols of th e underlyi ng operati ng system) . Client a pplication s using th e event-dr iven inter face can i ntercept e xternal en tity retri eval by th e parser a nd impleme nt support for these protocols if desire d.
	17191	File Acces s
	17192	The parser uses the Kernel fun ction FTG^ %ZISH for file acces s. This fu nction rea ds the ent ire conten ts of a fi le into an M global. There are several n uances to this funct ion that m anifest th emselves i n parser o peration:
	17193	Files are opened wit h a time-o ut paramet er. If an attempt is made to a ccess a no n-existent file, the re is a de lay of a f ew seconds before th e error is signaled.
	17194	Files are accessed i n text mod e. The res ult is tha t certain imbedded c ontrol cha racters ar e stripped from the input stre am and nev er detecte d by the p arser. Bec ause these control c haracters are disall owed by XM L, the par ser does n ot report such docum ents as no n-conformi ng.
	17195	A line fee d/carriage return se quence at the end of a documen t is strip ped and no t presente d to the p arser. Onl y in rare circumstan ces would this be co nsidered s ignificant data, but in the st rictest se nse should be preser ved.
	17196	Entity Sub stitutions Text
	17197	The parser allows ex ternal ent ities to c ontain sub stitution text that in some ca ses would violate XM L rules th at state t hat a docu ment must be conform ing in the absence o f resolvin g such ref erences. I n other wo rds, XML s tates that a non-val idating pa rser shoul d be able to verify that a doc ument is c onforming without pr ocessing e xternal en tities. Th is restric tion const rains how token stre ams can be continued across en tities. Th e parser r ecognizes most, but not all, o f these re strictions . The effe ct is that the parse r is more lax in all owing cert ain kinds of entity substituti ons.
	17198	Enforcing Whitespace
	17199	Parsers va ry in how they enfor ce whitesp ace that i s designat ed as requ ired by th e XML spec ification. This pars er flags t he absence of any re quired whi tespace as a conform ance error , even in situations where the absence o f such whi tespace wo uld not in troduce sy ntactic am biguity. T he result is that th is parser rejects so me documen ts that ma y be accep ted by oth er parsers .
	17200	Applicatio n Programm ing Interf ace (API)
	17201	The Toolki t VistA XM L Parser A pplication Programmi ng Interfa ces (APIs) have been developed to assist you in cr eating an XML docume nt.
	17202	Integratio n Control Registrati on #3561 d efines the various c allable en try points in the MX MLDOM rout ine. These APIs are based on t he W3C’s D ocument Ob ject Model (DOM) spe cification . It first builds an “in-memor y” image o f the full y parsed a nd validat ed documen t and then provides a set of m ethods to permit str uctured tr aversal of the docum ent and ex traction o f its cont ents. This API is ac tually lay ered on to p of the e vent-drive n API. In other word s, it is a ctually a client of the event- driven API that in t urn acts a s a server to anothe r client a pplication .
	17203	Several AP Is are ava ilable for developer s to work with the E Xtensible Markup Lan guage (XML ). These A PIs are de scribed be low.
	17204	$$ATTRIB^M XMLDOM(): XML—Get Fi rst or Nex t Node Att ribute Nam e
	17205	Reference Type:Suppo rted
	17206	Category:X ML Parser (VistA)
	17207	ICR #:3561
	17208	Descriptio n:This ext rinsic fun ction retu rns the fi rst or nex t attribut e associat ed with th e specifie d node.
	17209	Format:$$A TTRIB^MXML DOM(handle ,node[,att rib])
	17210	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17211	node:(requ ired) The node (inte ger) whose attribute name is b eing retri eved.
	17212	attrib:(op tional) Th e name (st ring) of t he last at tribute re trieved by this call . If null or missing , the firs t attribut e associat ed with th e specifie d node is returned. Otherwise, the next attribute in the lis t is retur ned.
	17213	Output:ret urns:Retur ns:
	17214	Name (stri ng) of the first or next attri bute assoc iated with the speci fied node.
	17215	Null if th ere are no ne remaini ng.
	17216
	17217	$$CHILD^MX MLDOM(): X ML—Get Par ent Node’s First or Next Child
	17218	Reference Type:Suppo rted
	17219	Category:X ML Parser (VistA)
	17220	ICR #:3561
	17221	Descriptio n:This ext rinsic fun ction retu rns the no de of the first or n ext child of a given parent no de, or zer o (0) if t here are n one remain ing.
	17222	Format:$$C HILD^MXMLD OM(handle, parent[,ch ild])
	17223	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17224	parent:(re quired) Th e node (in teger) who se childre n are bein g retrieve d.
	17225	child:(opt ional) If specified, this is t he last ch ild node ( integer) r etrieved. The functi on returns the next child in t he list. I f the para meter is z ero or mis sing, the first chil d is retur ned.
	17226	Output:ret urns:Retur ns:
	17227	Child Node —The next child node (integer) .
	17228	Zero (0)—I f there ar e none rem aining.
	17229
	17230	$$CMNT^MXM LDOM(): XM L—Extract Comment Te xt (True/F alse)
	17231	Reference Type:Suppo rted
	17232	Category:X ML Parser (VistA)
	17233	ICR #:3561
	17234	Descriptio n:This ext rinsic fun ction extr acts comme nt text as sociated w ith the sp ecified no de.
	17235	Format:$$C MNT^MXMLDO M(handle,n ode,text)
	17236	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17237	node:(requ ired) The node (inte ger) in th e document tree that is being referenced by this A PI.
	17238	text:(requ ired) This input par ameter (st ring) must contain a closed lo cal or glo bal array reference that is to receive t he text. T he specifi ed array i s deleted before bei ng populat ed.
	17239	Output:ret urns:Retur ns a Boole an value:
	17240	True (non- zero)—Text was retri eved.
	17241	False (zer o)—Text wa s not retr ieved.
	17242	CMNT^MXMLD OM(): XML— Extract Co mment Text (True/Fal se)
	17243	Reference Type:Suppo rted
	17244	Category:X ML Parser (VistA)
	17245	ICR #:3561
	17246	Descriptio n:This API extracts comment te xt associa ted with t he specifi ed node.
	17247	Format:$$C MNT^MXMLDO M(handle,n ode,text)
	17248	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17249	node:(requ ired) The node (inte ger) in th e document tree that is being referenced by this A PI.
	17250	text:(requ ired) This input par ameter (st ring) must contain a closed lo cal or glo bal array reference that is to receive t he text. T he specifi ed array i s deleted before bei ng populat ed.
	17251	Output:ret urns:Retur ns a Boole an value:
	17252	True (non- zero)—Text was retri eved.
	17253	False (zer o)—Text wa s not retr ieved.
	17254
	17255	DELETE^MXM LDOM(): XM L—Delete D ocument In stance
	17256	Reference Type:Suppo rted
	17257	Category:X ML Parser (VistA)
	17258	ICR #:3561
	17259	Descriptio n:This API deletes t he specifi ed documen t instance . A client applicati on should always cal l this API when fini shed with a document instance.
	17260	Format:DEL ETE^MXMLDO M(handle)
	17261	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17262	Output:non e.
	17263
	17264	$$EN^MXMLD OM(): XML— Initial Pr ocessing o f XML Docu ment, Buil d In-memor y Image
	17265	Reference Type:Suppo rted
	17266	Category:X ML Parser (VistA)
	17267	ICR #:3561
	17268	Descriptio n:This ext rinsic fun ction perf orms initi al process ing of the XML docum ent. The c lient appl ication mu st first c all this e ntry point to build the in-mem ory image of the doc ument befo re the rem aining met hods can b e applied. The retur n value is a handle to the doc ument inst ance that was create d and is u sed by the remaining API calls to identi fy a speci fic docume nt instanc e. The par ameters fo r this ent ry point a re listed by type, r equirement (yes or n o), and de scription.
	17269	Format:$$E N^MXMLDOM( doc[,opt])
	17270	Input Para meters:doc :(required ) This str ing is eit her a clos ed referen ce to a gl obal root containing the docum ent or a f ilename an d path ref erence ide ntifying t he documen t on the h ost system . If a glo bal root i s passed, the docume nt either must be st ored in st andard VA FileMan wo rd-process ing format or may oc cur in seq uentially numbered n odes below the root node. Thus , if the g lobal refe rence is “ ^XYZ”, the global mu st be of o ne of the following formats:
	17271	^XYZ(1,0) = “LINE 1” ^XYZ(2,0) = “LINE 2” ...
	17272	Or:
	17273	^XYZ(1) = “LINE 1”^X YZ(2) = “L INE 2” ...
	17274	opt:(optio nal) This string is a list of option fla gs that co ntrol pars er behavio r. Recogni zed option flags are :
	17275	W—Do not r eport warn ings to th e client.
	17276	V—Validate the docum ent. If no t specifie d, the par ser only c hecks for conformanc e.
	17277	1—Terminat e parsing on encount ering a va lidation e rror. (By default, t he parser terminates only when a conform ance error is encoun tered.)
	17278	0—Terminat e parsing on encount ering a wa rning.
	17279	Output:ret urns:Retur ns:
	17280	Successful —A non-zer o handle o f the docu ment insta nce if par sing compl eted succe ssfully.
	17281	Unsuccessf ul—Zero ha ndle of do cument ins tance.
	17282	This handl e is passe d to all o ther API m ethods to indicate w hich docum ent instan ce is bein g referenc ed. This a llows for multiple d ocument in stances to be proces sed concur rently.
	17283
	17284	$$NAME^MXM LDOM(): XM L—Get Elem ent Name
	17285	Reference Type:Suppo rted
	17286	Category:X ML Parser (VistA)
	17287	ICR #:3561
	17288	Descriptio n:This ext rinsic fun ction retr ieves the name of th e element at the spe cified nod e within t he documen t parse tr ee.
	17289	Format:$$N AME^MXMLDO M(handle,n ode)
	17290	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17291	node:(requ ired) The node (inte ger) for w hich the a ssociated element na me is bein g retrieve d.
	17292	Output:ret urns:Retur ns the nam e (string) of the el ement asso ciated wit h the spec ified node .
	17293
	17294	$$PARENT^M XMLDOM(): XML—Get Pa rent Node
	17295	Reference Type:Suppo rted
	17296	Category:X ML Parser (VistA)
	17297	ICR #:3561
	17298	Descriptio n:This ext rinsic fun ction retu rns the pa rent node of the spe cified nod e, or zero (0) if th ere is non e.
	17299	Format:$$P ARENT^MXML DOM(handle ,node)
	17300	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17301	node:(requ ired) The node (inte ger) in th e document tree whos e parent i s being re trieved.
	17302	Output:ret urns:Retur ns:
	17303	Parent Nod e—The pare nt node (s tring) of the specif ied node.
	17304	Zero (0)—I f there is no parent .
	17305
	17306	$$SIBLING^ MXMLDOM(): XML—Get S ibling Nod e
	17307	Reference Type:Suppo rted
	17308	Category:X ML Parser (VistA)
	17309	ICR #:3561
	17310	Descriptio n:This ext rinsic fun ction retu rns the no de of the specified node’s imm ediate sib ling, or z ero (0) if there is none.
	17311	Format:$$S IBLING^MXM LDOM(handl e,node)
	17312	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17313	node:(requ ired) The node (inte ger) in th e document tree whos e sibling is being r etrieved.
	17314	Output:ret urns:Retur ns:
	17315	Node—The n ode (integ er) corres ponding to the immed iate sibli ng of the specified node.
	17316	Zero (0)—I f there is no node ( integer) c orrespondi ng to the immediate sibling of the speci fied node.
	17317
	17318	$$TEXT^MXM LDOM(): XM L—Extract Non-markup Text (Tru e/False)
	17319	Reference Type:Suppo rted
	17320	Category:X ML Parser (VistA)
	17321	ICR #:3561
	17322	Descriptio n:This ext rinsic fun ction extr acts non-m arkup text associate d with the specified node.
	17323	Format:$$T EXT^MXMLDO M(handle,n ode,text)
	17324	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17325	node:(requ ired) The node (inte ger) in th e document tree that is being referenced by this A PI.
	17326	text:(requ ired) This input par ameter (st ring) must contain a closed lo cal or glo bal array reference that is to receive t he text. T he specifi ed array i s deleted before bei ng populat ed.
	17327	Output:ret urns:Retur ns a Boole an value:
	17328	True (non- zero)—Text was retri eved.
	17329	False (zer o)—Text wa s not retr ieved.
	17330
	17331	TEXT^MXMLD OM(): XML— Extract No n-markup T ext (True/ False)
	17332	Reference Type:Suppo rted
	17333	Category:X ML Parser (VistA)
	17334	ICR #:3561
	17335	Descriptio n:This API extracts non-markup text asso ciated wit h the spec ified node .
	17336	Format:TEX T^MXMLDOM( handle,nod e,text)
	17337	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17338	node:(requ ired) The node (inte ger) in th e document tree that is being referenced by this A PI.
	17339	text:(requ ired) This input par ameter (st ring) must contain a closed lo cal or glo bal array reference that is to receive t he text. T he specifi ed array i s deleted before bei ng populat ed.
	17340	Output:ret urns:Retur ns a Boole an value:
	17341	True (non- zero)—Text was retri eved.
	17342	False (zer o)—Text wa s not retr ieved.
	17343
	17344	$$VALUE^MX MLDOM(): X ML—Get Att ribute Val ue
	17345	Reference Type:Suppo rted
	17346	Category:X ML Parser (VistA)
	17347	ICR #:3561
	17348	Descriptio n:This ext rinsic fun ction retu rns the va lue associ ated with the named attribute.
	17349	Format:$$V ALUE^MXMLD OM(handle, node[,attr ib])
	17350	Input Para meters:han dle:(requi red) The v alue (inte ger) retur ned by the $$EN^MXML DOM(): XML —Initial P rocessing, Build In- memory Ima ge API, wh ich create d the in-m emory docu ment image .
	17351	node:(requ ired) The node (inte ger) whose attribute value is being retr ieved.
	17352	attrib:(op tional) Th e name of the attrib ute (strin g) whose v alue is be ing retrie ved by thi s API.
	17353	Output:ret urns:Retur ns the val ue associa ted with t he specifi ed attribu te.
	17354
	17355	EN^MXMLPRS E(): XML—E vent Drive n API
	17356	Reference Type:Suppo rted
	17357	Category:X ML Parser (VistA)
	17358	ICR #:4149
	17359	Descriptio n:This API is an eve nt-driven interface that is ba sed on the well-esta blished Si mple API f or XML (SA X) interfa ce employe d by many XML parser s. This AP I has a si ngle metho d.In this implementa tion, a cl ient appli cation pro vides a sp ecial hand ler for ea ch parsing event of interest. When the c lient invo kes the pa rser, it c onveys not only the document t o be parse d, but als o the entr y points f or each of its event handlers. As the pa rser progr esses thro ugh the do cument, it invokes t he client’ s handlers for each parsing ev ent for wh ich a hand ler has be en registe red.
	17360	Format:EN^ MXMLPRSE(d oc,cbk[,op t])
	17361	Input Para meters:doc :(required ) This str ing is eit her a clos ed referen ce to a gl obal root containing the docum ent or a f ilename an d path ref erence ide ntifying t he documen t on the h ost system . If a glo bal root i s passed, the docume nt either must be st ored in st andard VA FileMan wo rd-process ing format or may oc cur in seq uentially numbered n odes below the root node. Thus , if the g lobal refe rence is “ ^XYZ”, the global mu st be of o ne of the following formats:
	17362	^XYZ(1,0) = “LINE 1” ^XYZ(2,0) = “LINE 2” ...
	17363	Or:
	17364	^XYZ(1) = “LINE 1”^X YZ(2) = “L INE 2”...
	17365	cbk:(requi red) This is a local array, pa ssed by re ference th at contain s a list o f parse ev ents and t he entry p oints for the handle rs of thos e events. The format for each entry is:
	17366	CBK(<event type>) = <entry poi nt>
	17367	The entry point must reference a valid e ntry point in an exi sting M ro utine and should be of the for mat tag^ro utine. The entry sho uld not co ntain any formal par ameter ref erences. T he applica tion devel oper is re sponsible for ensuri ng that th e actual e ntry point contains the approp riate numb er of form al paramet ers for th e event ty pe. For ex ample, cli ent applic ation migh t register its START ELEMENT ev ent handle r as follo ws:
	17368	CBK(“START ELEMENT”) = “STELE^C LNT”
	17369	The actual entry poi nt in the CLNT routi ne must in clude two formal par ameters as in the fo llowing ex ample:
	17370	STELE(ELE, ATR) <hand ler code>
	17371	REF: For t he types o f supporte d events a nd their r equired pa rameters, see the “D etails” se ction.
	17372	opt:(optio nal) This is a list of option flags (str ing) that control pa rser behav ior. Recog nized opti on flags a re:
	17373	W—Do not r eport warn ings to th e client.
	17374	V—Validate the docum ent. If no t specifie d, the par ser only c hecks for conformanc e.
	17375	1—Terminat e parsing on encount ering a va lidation e rror. (By default, t he parser terminates only when a conform ance error is encoun tered.)
	17376	0—Terminat e parsing on encount ering a wa rning.
	17377	Output:ret urns:Retur ns the XML parsed st ring.
	17378
	17379	Details
	17380	The VistA XML Parser recognize s the even t types li sted in Ta ble 46:
	17381	Table 46: XML Parser —Event typ es
	17382	Event Type
	17383	Parameters
	17384	Descriptio n
	17385	STARTDOCUM ENT
	17386	None
	17387	Notifies t he client that docum ent parsin g has comm enced.
	17388	ENDDOCUMEN T
	17389	None
	17390	Notifies t he client that docum ent parsin g has comp leted.
	17391	DOCTYPE
	17392	ROOTPUBIDS YSID
	17393	Notifies t he client that a DOC TYPE decla ration has been enco untered. T he name of the docum ent root i s given by ROOT. The public an d system i dentifiers of the ex ternal doc ument type definitio n are give n by PUBID and SYSID , respecti vely.
	17394	STARTELEME NT
	17395	NAMEATTRLI ST
	17396	An element (tag) has been enco untered. T he name of the eleme nt is give n in NAME. The list of attribu tes and th eir values is provid ed in the local arra y ATTRLST in the for mat:
	17397	ATTRLST(<n ame>) = <v alue>
	17398	ENDELEMENT
	17399	NAME
	17400	A closing element (t ag) has be en encount ered. The name of th e element is given i n NAME.
	17401	CHARACTERS
	17402	TEXT
	17403	Non-markup content h as been en countered. TEXT cont ains the t ext. Line breaks wit hin the or iginal doc ument are represente d as carri age return /line feed character sequences . The pars er does no t necessar ily pass a n entire l ine of the original document t o the clie nt with ea ch event o f this typ e.
	17404	PI
	17405	TARGETTEXT
	17406	The parser has encou ntered a p rocessing instructio n. TARGET is the tar get applic ation for the proces sing instr uction. TE XT is a lo cal array containing the param eters for the instru ction.
	17407	EXTERNAL
	17408	SYSIDPUBID GLOBAL
	17409	The parser has encou ntered an external e ntity refe rence whos e system a nd public identifier s are give n by SYSID and PUBID , respecti vely. If t he event h andler ele cts to ret rieve the entity rat her than a llowing th e parser t o do so, i t should p ass the gl obal root of the ret rieved ent ity in the GLOBAL pa rameter. I f the even t handler wishes to suppress r etrieval o f the enti ty altoget her, it sh ould set b oth SYSID and PUBID to null.
	17410	NOTATION
	17411	NAMESYSIDP UBIC
	17412	The parser has encou ntered a n otation de claration. The notat ion name i s given by NAME. The system an d public i dentifiers associate d with the notation are given by SYSID a nd PUBIC, respective ly.
	17413	COMMENT
	17414	TEXT
	17415	The parser has encou ntered a c omment. TE XT is the text of th e comment.
	17416	ERROR
	17417	ERR
	17418	The parser has encou ntered an error duri ng the pro cessing of a documen t. ERR is a local ar ray contai ning infor mation abo ut the err or. The fo rmat is:
	17419	ERR(“SEV”) = Severit y of the e rror where zero (0) is a warni ng, 1 is a validatio n error, a nd 2 is a conformanc e error.
	17420	ERR(“MSG”) —Brief tex t descript ion of the error.
	17421	ERR(“ARG”) —The token value the triggered the error (optional ).
	17422	ERR(“LIN”) —The numbe r of the l ine being processed when the e rror occur red.
	17423	ERR(“POS”) —The chara cter posit ion within the line where the error occu rred.
	17424	ERR(“XML”) —The origi nal docume nt text of the line where the error occu rred.
	17425
	17426	Example
	17427	This is a simple exa mple of ho w to use t he VistA X ML Parser with an XM L document (file). T he XML fil e contains a parent node named BOOKS. Ne sted withi n that par ent node a re child n odes named TITLE and AUTHOR.
	17428	Remember t he followi ng:
	17429	The parent node is t he node wh ose child nodes are being retr ieved.
	17430	The child node, if s pecified, is the las t child no de retriev ed. The fu nction ret urns the n ext child in the lis t. If the parameter is zero or missing, the first child is r eturned.
	17431	A sample c lient of t he event-d riven API is provide d in the r outine MXM LTEST. Thi s routine has an ent ry point E N(DOC,OPT) , where DO C and OPT are the sa me paramet ers as des cribed abo ve for the parser en try point. This samp le applica tion simpl y prints a summary o f the pars ing events as they o ccur.
	17432	Create an XML File:
	17433	Figure 153 : VistA XM L Parser U se—Example : Create X ML file
	17434	^TMP($J,1) = <?xml v ersion=‘1. 0’?>
	17435	^TMP($J,2) = <!DOCTY PE BOOK>
	17436	^TMP($J,3) = <BOOK>
	17437	^TMP($J,4) = <TITLE> Design Pat terns</TIT LE>
	17438	^TMP($J,5) = <AUTHOR >Author1</ AUTHOR>
	17439	^TMP($J,6) = <AUTHOR >Author2</ AUTHOR>
	17440	^TMP($J,7) = <AUTHOR >Author3</ AUTHOR>
	17441	^TMP($J,8) = <AUTHOR >Author4</ AUTHOR>
	17442	^TMP($J,9) = </BOOK>
	17443
	17444	Invoke Sim ple API fo r XML (SAX ) Interfac e:
	17445	Figure 154 : VistA XM L Parser U se Example —Invoke SA X Interfac e
	17446	D EN^MXMLT EST($NA(^T MP($J)),"V ")
	17447
	17448	Check Docu ment Objec t Model (D OM) Interf ace:
	17449	Figure 155 : VistA XM L Parser U se Example —Check DOM Interface
	17450	>S HDL=$$E N^MXMLDOM( $NA(^TMP($ J)))
	17451
	17452	Write the name of th e first no de.
	17453	Write the name of th e first no de.
	17454	>W $$NAME^ MXMLDOM(HD L,1)
	17455	BOOK
	17456
	17457	Get the ch ild of the node.
	17458	Get the ch ild of the node.
	17459	>S CHD=$$C HILD^MXMLD OM(HDL,1)
	17460
	17461	Write the child name .
	17462	Write the child name .
	17463	>W $$NAME^ MXMLDOM(HD L,CHD)
	17464	TITLE
	17465
	17466
	17467	Get the te xt of the child.
	17468	Get the te xt of the child.
	17469	>W $$TEXT^ MXMLDOM(HD L,CHD,$NA( VV))
	17470	1
	17471
	17472	>ZW VV
	17473	VV(1)=Desi gn Pattern s
	17474
	17475	List All S ibling Nod es:
	17476	Figure 156 : VistA XM L Parser U se Example —List All Sibling No des
	17477	>S CHD=$$C HILD^MXMLD OM(HDL,1)
	17478	>S SIB=CHD
	17479	>F S SIB= $$SIBLING^ MXMLDOM(HD L,SIB) Q:S IB'>0 W ! ,SIB,?4,$$ NAME^MXMLD OM(HDL,SIB )
	17480	3 AUTHOR
	17481	4 AUTHOR
	17482	5 AUTHOR
	17483	6 AUTHOR
	17484	>
	17485
	17486	$$SYMENC^M XMLUTL(): XML—Replac e XML Symb ols with X ML Encodin g
	17487	Reference Type:Suppo rted
	17488	Category:X ML Parser (VistA)
	17489	ICR #:4153
	17490	Descriptio n:This ext rinsic fun ction repl aces reser ved Extens ible Marku p Language (XML) sym bols in a string wit h their XM L encoding for strin gs used in an XML me ssage.
	17491	Format:$$S YMENC^MXML UTL(str)
	17492	Input Para meters:str :(required ) String t o be encod ed in an X ML message .
	17493	Output:ret urns:Retur ns the inp ut string with XML e ncoding re placing re served XML symbols.
	17494	Example
	17495	>S X=$$SYM ENC^MXMLUT L(“This li ne isn’t & ”“<XML>”“ safe as is .”)
	17496
	17497	>W X
	17498	This line isn&os;t & amp;" <XML&gt ;" sa fe as is.
	17499
	17500	$$XMLHDR^M XMLUTL: XM L—Get XML Message He ader
	17501	Reference Type:Suppo rted
	17502	Category:X ML Parser (VistA)
	17503	ICR #:4153
	17504	Descriptio n:This ext rinsic fun ction retu rns a stan dard Exten sible Mark up Languag e (XML) he ader for e ncoding XM L messages .
	17505	Format:$$X MLHDR^MXML UTL
	17506	Input Para meters:non e.
	17507	Output:ret urns:Retur ns a stand ard XML he ader.
	17508
	17509	Example
	17510	>S X=$$XML HDR^MXMLUT L
	17511
	17512	>W X
	17513	<?xml vers ion=“1.0” encoding=“ utf-8” ?>
	17514
	17515
	17516	^XTMP Glob al: Develo per Tools
	17517	Overview
	17518	There is a recurring need by V istA softw are to sto re data in a transla ted global for relat ively shor t periods of time. H owever, th is data ne eds to be accumulate d for a pe riod longe r than an individual user's lo gon sessio n and long er than th e time a s pecific pr ocess/job might run. The ^UTIL ITY, ^TMP and ^XUTL globals do not meet the basic requiremen ts for sto ring this type of da ta due to the follow ing:
	17519	These glob als are no t translat ed, and th us, cannot be relied upon for transferri ng data fr om one job to anothe r.
	17520	The data i s not stor ed for exc essively l ong period s of time and is con stantly be ing proces sed and pu rged.
	17521	The data i s stored i n an inter mediate fo rm, tempor arily, so that it ca n be furth er process ed in an e fficient m anner.
	17522	The origin al data is stored in a VA File Man file f rom which the tempor ary data c an be recr eated, or on another system (u sually non -VistA) fr om which i t can be r esent, if necessary. Hence, th e creation of a VA F ileMan fil e, while f easible, w ould add u nnecessary overhead to the Vis tA systems .
	17523	Therefore, the Stand ards and C onventions Committee (SACC) as ked Kernel to establ ish the ^X TMP global , which ca n be used by any Vis tA softwar e applicat ion. This global is dynamic in size and activity, with one c opy access ible to al l members of a UCI, and should be placed according ly.
	17524	CAUTION: T he ^XTMP g lobal shou ld not be used for l ong-term s torage of data; data requiring long-term storage s hould be p laced with in a file. The ^XTMP global sh ould only be used fo r near-ter m storage needs and should res pect size constraint s.
	17525	Rules for Use of the ^XTMP Glo bal
	17526	The struct ure of eac h top node of the ^X TMP global has the f ollowing f ormat:
	17527	^XTMP(name spaced- su bscript,0) =purge dat e^createda te^optiona l descript ive inform ation
	17528	(Both date s must be in VA File Man intern al date fo rmat.)
	17529	As per the Standards and Conve ntions (SA C, Section 2.11.8), developers are encou raged to i nclude oth er descrip tive infor mation on the third piece of t he 0 node of the ^XT MP global (e.g., tas k descript ion and cr eator DUZ) .
	17530	First Subs cript Must be Namesp aced—The f irst subsc ript of th e ^XTMP gl obal must be namespa ced; howev er, other characters can follo w the name space. For example, if the nam espace for the softw are is "RA ," the fir st subscri pt could b e "RA"_DUZ , "RA"_lit eral, "RA" _$J, etc. This allow s the deve loper to u se the glo bal in dif ferent par ts of the software.
	17531	0 Node Mus t Exist—Th ere must b e a 0 node for the g lobal in w hich the f irst piece contains the PURGE DATE in VA FileMan i nternal da te format, and the s econd piec e contains the CREAT E DATE in VA FileMan internal date forma t. For exa mple:
	17532	^XTMP("RA1 ",0)=29204 16^2920401
	17533	KILL ^XTMP After Use —The devel oper is re sponsible for KILLin g ^XTMP(x) when its use is com plete (whe re "x" is their name spaced sub script).
	17534	Code Clean up—Kernel has includ ed the nec essary cod e in the X Q82 routin e to clean up the ^X TMP global (e.g., ^X TMP("RA1") . It KILLs this glob al under a ny of the following conditions :
	17535	There is n o 0 node ( e.g., ^XTM P("RA1",0) .
	17536	The 0 node does not contain a purge date as the fi rst piece.
	17537	The date i n the firs t piece of the 0 nod e is the s ame as or before the system da te.
	17538	SAC Exempt ions
	17539	As of May 17, 2002, the Standa rds and Co nventions (SAC) docu ment has t he followi ng exempti ons regard ing the ^X TMP global :
	17540	Section 2. 3.2.1—Subs cripts use d in the ^ TMP and ^X TMP global s can be l owercase.
	17541	Section 2. 3.2.5—The ^TMP, ^UTI LITY, and ^XTMP glob als do not have to b e VA FileM an compati ble.
	17542	Section 2. 3.2.5.2—Th e ^XTMP gl obal will be transla ted, with one copy f or the ent ire VistA production system at each site .
	17543	Section 2. 7.3.3—All documented temporary scratch g lobal node s (e.g., ^ TMP and ^U TILITY) ar e created by a calle d supporte d referenc e, with th e exceptio n of ^XTMP global da ta.
	17544	Section 2. 7.3.4—All local vari ables, loc ks, and sc ratch glob al nodes ( except ^XT MP, or oth er scratch globals d esigned to be passed between p arts of a package) a re created by the ap plication.
	17545	A new exte nsion must be added to the SAC stating t hat this g lobal shou ld be used as a scra tch area w hen a tran slated scr atch globa l is requi red by sof tware appl ications.
	17546	REF: To vi ew the ent ire SAC do cument, se e the SACC website a t: http:// vaww.vista .med. DOMAIN /sacc/
	17547
	17548
	17549	Glossary
	17550
	17551	Term
	17552	Definition
	17553	ALERTS
	17554	An alert n otifies on e or more users of a matter re quiring im mediate at tention. A lerts func tion as br ief notice s that are distinct from mail messages o r triggere d bulletin s.
	17555	Alerts are designed to provide interacti ve notific ation of p ending com puting act ivities (e .g., the n eed to reo rder suppl ies or rev iew a pati ent’s clin ical test results). Along with the alert message i s an indic ation that the View Alerts com mon option should be chosen to take furt her action .
	17556	An alert i ncludes an y specific ations mad e by the d eveloper w hen design ing the al ert. This minimally includes t he alert m essage and the list of recipie nts (an in formation- only alert ). It can also inclu de an aler t action, software a pplication identifie r, alert f lag, and a lert data. Alerts ar e stored i n the ALER T file (#8 992).
	17557	ALERT ACTI ON
	17558	The comput ing activi ty that ca n be assoc iated with an alert (i.e., an option [XQ AOPT input variable] or routin e [XQAROU input vari able]).
	17559	ALERT DATA
	17560	An optiona l string t hat the de veloper ca n define w hen creati ng the ale rt. This s tring is r estored in the XQADA TA input v ariable wh en the ale rt action is taken.
	17561	ALERT FLAG
	17562	An optiona l tool cur rently con trolled by the Alert Handler t o indicate how the a lert shoul d be proce ssed (XQAF LG input v ariable).
	17563	ALERT HAND LER
	17564	The name o f the mech anism by w hich alert s are stor ed, presen ted to the user, pro cessed, an d deleted. The Alert Handler i s a part o f Kernel, in the XQA L namespac e.
	17565	ALERT IDEN TIFIER
	17566	A three-se micolon pi ece identi fier, comp osed of th e original Package I dentifier (described below) as the first piece; th e DUZ of t he alert c reator as the second piece; an d the date and time (in VA Fil eMan forma t) when th e alert wa s created as the thi rd piece. The Alert Identifier is create d by the A lert Handl er and uni quely iden tifies an alert.
	17567	ALERT MESS AGE
	17568	One line o f text tha t is displ ayed to th e user (th e XQAMSG i nput varia ble).
	17569	ALPHA TEST ING
	17570	In VA term inology, A lpha testi ng is when a VistA t est softwa re applica tion is ru nning in a site’s ac count.
	17571	AUDIT ACCE SS
	17572	A user’s a uthorizati on to mark the infor mation sto red in a c omputer fi le to be a udited.
	17573	AUDITING
	17574	Monitoring computer usage such as change s to the d atabase an d other us er activit y. Audit d ata can be logged in a number of VA File Man and Ke rnel files .
	17575	AUTO MENU
	17576	An indicat ion to Men u Manager that the c urrent use r’s menu i tems shoul d be displ ayed autom atically. When AUTO MENU is no t in effec t, the use r must ent er a quest ion mark a t the menu ’s select prompt to see the li st of menu items.
	17577	BETA TESTI NG
	17578	In VA term inology, B eta testin g is when a VistA te st softwar e applicat ion is run ning in a Production account.
	17579	CAPACITY M ANAGEMENT
	17580	The proces s of asses sing a sys tem’s capa city and e valuating its effici ency relat ive to wor kload in a n attempt to optimiz e system p erformance . Kernel p rovides se veral util ities.
	17581	CARET
	17582	A symbol e xpressed a s ^ (caret ). In many M systems , a caret is used as an exitin g tool fro m an optio n. Also re ferred to as the “up -arrow” sy mbol.
	17583	CHECKSUM
	17584	A numeric value that is the re sult of a mathematic al computa tion invol ving the c haracters of a routi ne or file .
	17585	CIPHER
	17586	A system t hat arbitr arily repr esents eac h characte r as one o r more oth er charact ers.
	17587	(See also: ENCRYPTIO N.)
	17588	COMMON MEN U
	17589	Options th at are ava ilable to all users. Entering two questi on marks ( “??”) at t he menu’s select pro mpt displa ys any SEC ONDARY MEN U OPTIONS available to the sig ned-on use r along wi th the com mon option s availabl e to all u sers.
	17590	COMPILED M ENU SYSTEM (^XUTL GL OBAL)
	17591	Job-specif ic informa tion that is kept on each CPU so that it is readil y availabl e during t he user’s session. I t is store d in the ^ XUTL globa l, which i s maintain ed by the menu syste m to hold commonly r eferenced informatio n. The use r’s place within the menu tree s is store d, for exa mple, to e nable navi gation via menu jump ing.
	17592	COMPUTED F IELD
	17593	This field takes dat a from oth er fields and perfor ms a prede termined m athematica l function (e.g., ad ding two c olumns tog ether). Yo u do not, however, s ee the res ults of th e mathemat ical funct ion on the screen. O nly when y ou are pri nting or d isplaying informatio n on the s creen do y ou see the results f or this ty pe of fiel d.
	17594	DEVICE HAN DLER
	17595	The Kernel module th at provide s a mechan ism for ac cessing pe ripherals and using them in co ntrolled w ays (e.g., user acce ss to prin ters or ot her output devices).
	17596	DIFROM
	17597	VA FileMan utility t hat gather s all soft ware compo nents and changes th em into ro utines (na mespaceI* routines) so that th ey can be exported a nd install ed in anot her VA Fil eMan envir onment.
	17598	DOUBLE QUO TE (“)
	17599	A symbol u sed in fro nt of a Co mmon optio n’s menu t ext or syn onym to se lect it fr om the Com mon menu. For exampl e, the fiv e characte r string “ TBOX selec ts the Use r’s Toolbo x Common o ption.
	17600	DR STRING
	17601	The set of character s used to define the DR variab le when ca lling VA F ileMan. Si nce a seri es of para meters may be includ ed within quotes as a literal string, th e variable ’s definit ion is oft en called the DR str ing. To de fine the f ields with in an edit sequence, for examp le, the de veloper ma y specify the fields using a D R string r ather than an INPUT template.
	17602	DUZ(0)
	17603	A local va riable tha t holds th e FILE MAN AGER ACCES S CODE of the signed -on user.
	17604	ENCRYPTION
	17605	Scrambling data or m essages wi th a ciphe r or code so that th ey are unr eadable wi thout a se cret key. In some ca ses encryp tion algor ithms are one direct ional, tha t is, they only enco de and the resulting data cann ot be unsc rambled (e .g., Acces s and Veri fy codes).
	17606	FILE ACCES S SECURITY SYSTEM
	17607	Formerly k nown as Pa rt 3 of th e Kernel I nits. If t he File Ac cess Secur ity conver sion has b een run, f ile-level security f or VA File Man files is control led by Ker nel’s File Access Se curity sys tem, not b y VA FileM an Access codes (i.e ., FILE MA NAGER ACCE SS CODE fi eld).
	17608	FORCED QUE UING
	17609	A device a ttribute i ndicating that the d evice can only accep t queued t asks. If a job is se nt for for eground pr ocessing, the device rejects i t and prom pts the us er to queu e the task instead.
	17610	GO-HOME JU MP
	17611	A menu jum p that ret urns the u ser to the primary m enu presen ted at sig non. It is specified by enteri ng two car ets (“^^”) at the me nu’s selec t prompt. It resembl es the Rub ber-band J ump but wi thout an o ption spec ification after the carets.
	17612	HELP PROCE SSOR
	17613	A Kernel m odule that provides a system f or creatin g and disp laying onl ine docume ntation. I t is integ rated with in the men u system s o that hel p frames a ssociated with optio ns can be displayed with a sta ndard quer y at the m enu’s sele ct prompt.
	17614	HOST FILE SERVER (HF S)
	17615	A procedur e availabl e on layer ed systems whereby a file on t he host sy stem can b e identifi ed to rece ive output . It is im plemented by the Dev ice Handle r’s HFS de vice type.
	17616	INIT
	17617	Initializa tion of a software a pplication . INIT* ro utines are built by VA FileMan ’s DIFROM and, when run, recre ate a set of files a nd other s oftware co mponents.
	17618	JUMP
	17619	In VistA a pplication s, the Jum p command allows you to go fro m a partic ular field within an option to another f ield withi n that sam e option. You can al so Jump fr om one men u option t o another menu optio n without having to respond to all the p rompts in between. T o jump, ty pe a caret (“^”, upp ercase-6 k ey on most keyboards ) and then type the name of th e field or option to which you wish to j ump.
	17620	(See also GO-HOME JU MP, PHANTO M JUMP, RU BBER-BAND JUMP, or U P-ARROW JU MP.)
	17621	JUMP START
	17622	A logon pr ocedure wh ereby the user enter s the “Acc ess code;V erify code ;option” t o go immed iately to the target option, i ndicated b y its menu text or s ynonym. Th e jump syn tax can be used to r each an op tion withi n the menu trees by entering “ Access;Ver ify;^optio n”.
	17623	KERMIT
	17624	A standard file tran sfer proto col. It is supported by Kernel and can b e set up a s an alter nate edito r.
	17625	MANAGER AC COUNT
	17626	A UCI that can be re ferenced b y non-mana ger accoun ts (e.g., production accounts) . Like a l ibrary, th e MGR UCI holds perc ent routin es and glo bals (e.g. , ^%ZOSF) for shared use by ot her UCIs.
	17627	MENU CYCLE
	17628	The proces s of first visiting a menu opt ion by pic king it fr om a menu’ s list of choices an d then ret urning to the menu’s select pr ompt. Menu Manager k eeps track of inform ation (e.g ., the use r’s place in the men u trees) a ccording t o the comp letion of a cycle th rough the menu syste m.
	17629	MENU MANAG ER
	17630	The Kernel module th at control s the pres entation o f user act ivities (e .g., menu choices or options). Informati on about e ach user’s menu choi ces is sto red in the Compiled Menu Syste m, the ^XU TL global, for easy and effici ent access .
	17631	MENU SYSTE M
	17632	The overal l Menu Man ager logic as it fun ctions wit hin the Ke rnel frame work.
	17633	MENU TEMPL ATE
	17634	An associa tion of op tions as p athway spe cification s to reach one or mo re final d estination options. The final options mu st be exec utable act ivities an d not mere ly menus f or the tem plate to f unction. A ny user ca n define u ser-specif ic MENU te mplates vi a the corr esponding Common opt ion.
	17635	MENU TREES
	17636	The menu s ystem’s hi erarchical tree-like structure s that can be traver sed or nav igated, li ke pathway s, to give users eas y access t o various options.
	17637	PAC
	17638	Programmer Access Co de. An opt ional user attribute that can function a s a second level pas sword into Programme r mode.
	17639	PACKAGE ID ENTIFIER
	17640	An optiona l identifi er that th e develope r can use to identif y the aler t for such purposes as subsequ ent lookup and delet ion (XQAID input var iable).
	17641	PART 3 OF THE KERNEL INIT
	17642	See FILE A CCESS SECU RITY SYSTE M.
	17643	PATTERN MA TCH
	17644	A preset f ormula use d to test strings of data. Ref er to your system’s M Language Manuals f or informa tion on Pa ttern Matc h operatio ns.
	17645	PHANTOM JU MP
	17646	Menu jumpi ng in the background . Used by the menu s ystem to c heck menu pathway re strictions .
	17647	PRIMARY ME NUS
	17648	The list o f options presented at signon. Each user must have a PRIMARY MENU OPTI ON in orde r to sign on and rea ch Menu Ma nager. Use rs are giv en primary menus by system adm inistrator s. This me nu should include mo st of the computing activities the user needs.
	17649	PROGRAMMER ACCESS
	17650	Privilege to become a programm er on the system and work outs ide many o f the secu rity contr ols of Ker nel. Acces sing Progr ammer mode from Kern el’s menus requires having the developer ’s at-sign security code, whic h sets the variable DUZ()=@.
	17651	PROTOCOL
	17652	An entry i n the PROT OCOL file (#101). Us ed by the Order Entr y/Results Reporting (OE/RR) so ftware to support th e ordering of medica l tests an d other ac tivities. Kernel inc ludes seve ral protoc ol-type op tions for enhanced m enu displa ys within the OE/RR software.
	17653	PURGE INDI CATOR
	17654	Checked by the Alert Handler ( in the XQA KILL input variable) to determ ine whethe r an alert should be deleted, and whethe r deletion should be for the c urrent use r or for a ll users w ho might r eceive the alert.
	17655	QUEUING
	17656	Requesting that a jo b be proce ssed in th e backgrou nd rather than in th e foregrou nd within the curren t session. Kernel’s TaskMan mo dule handl es the que uing of ta sks.
	17657	QUEUING RE QUIRED
	17658	An option attribute that speci fies that the option must be p rocessed b y TaskMan (the optio n can only be queued ). The opt ion can be invoked a nd the job prepared for proces sing, but the output can only be generat ed during the specif ied time p eriods.
	17659	RESOURCE
	17660	A method t hat enable s sequenti al process ing of tas ks. The pr ocessing i s accompli shed with a RES devi ce type de signed by the applic ation deve loper and implemente d by syste m administ rators. Th e process is control led via th e RESOURCE file (#3. 54).
	17661	RUBBER-BAN D JUMP
	17662	A menu jum p used to go out to an option and then r eturn, in a bouncing motion. T he syntax of the jum p is two c arets (“^^ ”, upperca se-6 on mo st keyboar ds) follow ed by an o ption’s me nu text or synonym ( e.g., ^^Pr int Option File). If the two c arets are not follow ed by an o ption spec ification, the user is returne d to the p rimary men u.
	17663	(See also: GO-HOME J UMP.)
	17664	SCHEDULING OPTIONS
	17665	A way of o rdering Ta skMan to r un an opti on at a de signated t ime with a specified reschedul ing freque ncy (e.g., once per week).
	17666	SCROLL/NO SCROLL
	17667	The Scroll /No Scroll button (a lso called Hold Scre en) allows the user to “stop” (No Scroll ) the term inal scree n when lar ge amounts of data a re display ed too fas t to read and “resta rt” (Scrol l) when th e user wis hes to con tinue.
	17668	SECONDARY MENU OPTIO NS
	17669	Options as signed to individual users to tailor the ir menu ch oices. If a user nee ds a few o ptions in addition t o those av ailable on the prima ry menu, t he options can be as signed as secondary options. T o facilita te menu ju mping, sec ondary men us should be specifi c activiti es, not el aborate an d deep men u trees.
	17670	SECURE MEN U DELEGATI ON (SMD)
	17671	A controll ed system whereby me nus and ke ys can be allocated by people other than system ad ministrato rs (e.g., applicatio n coordina tors) who have been so authori zed. SMD i s a part o f Menu Man ager.
	17672	SERVER OPT ION
	17673	In VistA, an entry i n the OPTI ON file (# 19). An au tomated ma il protoco l that is activated by sending a message to the se rver with the “S.ser ver” synta x. A serve r option’s activity is specifi ed in the OPTION fil e (#19) an d can be t he running of a rout ine or the placement of data i nto a file .
	17674	SIGNON/SEC URITY
	17675	The Kernel module th at regulat es access to the men u system. It perform s a number of checks to determ ine whethe r access c an be perm itted at a particula r time. A log of sig nons is ma intained.
	17676	SPECIAL QU EUEING
	17677	An option attribute indicating that Task Man should automatic ally run t he option whenever t he system reboots.
	17678	SPOOLER
	17679	An entry i n the DEVI CE file (# 3.5). It u ses the as sociated o perating s ystem’s sp ool facili ty, whethe r it is a global, de vice, or h ost file. Kernel man ages spool ing so tha t the unde rlying OS mechanism is transpa rent. In a ny environ ment, the same metho d can be u sed to sen d output t o the spoo ler. Kerne l subseque ntly trans fers the t ext to a g lobal for subsequent despoolin g (printin g).
	17680	SYNONYM
	17681	In VistA, a field in the OPTIO N file (#1 9). Option s can be s elected by their men u text or synonym.
	17682	(See also: MENU TEXT .)
	17683	TASKMAN
	17684	The Kernel module th at schedul es and pro cesses bac kground ta sks (also called Tas k Manager) .
	17685	TIMED READ
	17686	The amount of time K ernel wait s for a us er respons e to an in teractive READ comma nd before starting t o halt the process.
	17687	UP-ARROW J UMP
	17688	In the men u system, entering a caret (“^ ”) followe d by an op tion name accomplish es a jump to the tar get option without n eeding to take the u sual steps through t he menu pa thway.
	17689	XINDEX
	17690	A Kernel u tility use d to verif y routines and other M code as sociated w ith a soft ware appli cation. Ch ecking is done accor ding to cu rrent ANSI MUMPS sta ndards and VistA pro gramming s tandards. This tool can be inv oked throu gh an opti on or from direct mo de (>D ^XI NDEX).
	17691	Z EDITOR ( ^%Z)
	17692	A Kernel t ool used t o edit rou tines or g lobals. It can be in voked with an option , or from direct mod e after lo ading a ro utine with >X ^%Z.
	17693	ZOSF GLOBA L (^%ZOSF)
	17694	The Operat ing System File—a ma nager acco unt global distribut ed with Ke rnel to pr ovide an i nterface b etween Vis tA softwar e and the underlying operating system. T his global is built during Ker nel instal lation whe n running the manage r setup ro utine (ZTM GRSET). Th e nodes of the globa l are fill ed-in with operating system-sp ecific cod e to enabl e interact ion with t he operati ng system. Nodes in the ^%ZOSF global ca n be refer enced by V istA appli cation dev elopers so that sepa rate versi ons of the software need not b e written for each o perating s ystem.
	17695	REF: For a list of c ommonly us ed terms a nd definit ions, see the OI&T M aster Glos sary VA In tranet Web site.For a list of c ommonly us ed acronym s, see the VA Acrony m Lookup I ntranet We bsite.
	17696
	17697
	17698	Index
	17699
	17700	$
	17701	$$%H^XLFDT , 503
	17702	$$ABS^XLFM TH, 529
	17703	$$ACCESS^X QCHK, 218
	17704	$$ACOS^XLF MTH, 530
	17705	$$ACOSDEG^ XLFMTH, 53 0
	17706	$$ACOSH^XL FHYPER, 52 3
	17707	$$ACOT^XLF MTH, 531
	17708	$$ACOTDEG^ XLFMTH, 53 1
	17709	$$ACOTH^XL FHYPER, 52 4
	17710	$$ACSC^XLF MTH, 532
	17711	$$ACSCDEG^ XLFMTH, 53 2
	17712	$$ACSCH^XL FHYPER, 52 4
	17713	$$ACTIVE^X UAF4, 121
	17714	$$ACTIVE^X USER, 467
	17715	$$ACTJ^%ZO SV, 262
	17716	$$ADD^XPDM ENU, 210
	17717	$$ADD^XPDP ROT, 213
	17718	$$ADD^XUSE RNEW, 290
	17719	$$ADDRESS^ XLFNSLK, 8 8
	17720	$$AESDECR^ XUSHSH, 48
	17721	$$AESENCR^ XUSHSH, 49
	17722	$$ASEC^XLF MTH, 533
	17723	$$ASECDEG^ XLFMTH, 53 3
	17724	$$ASECH^XL FHYPER, 52 5
	17725	$$ASIN^XLF MTH, 534
	17726	$$ASINDEG^ XLFMTH, 53 4
	17727	$$ASINH^XL FHYPER, 52 5
	17728	$$ASKSTOP^ %ZTLOAD, 3 33
	17729	$$ATAN^XLF MTH, 535
	17730	$$ATANDEG^ XLFMTH, 53 5
	17731	$$ATANH^XL FHYPER, 52 6
	17732	$$ATTRIB^M XMLDOM, 57 6
	17733	$$AVJ^%ZOS V, 263
	17734	$$B64DECD^ XUSHSH, 50
	17735	$$B64ENCD^ XUSHSH, 50
	17736	$$BASE^XLF UTL, 563
	17737	$$BLDNAME^ XLFNAME, 2 32
	17738	$$BSA^XLFM SMT, 549
	17739	$$CCD^XLFU TL, 564
	17740	$$CHECKAV^ XUSRB, 291
	17741	$$CHECKAV^ XUVERIFY, 297
	17742	$$CHILD^MX MLDOM, 577
	17743	$$CHKDGT^X USNPI, 254
	17744	$$CHKSUM^X USESIG1, 9 1
	17745	$$CIRN^XUA F4, 122
	17746	$$CJ^XLFST R, 554
	17747	$$CLEANC^X LFNAME, 23 4
	17748	$$CMNT^MXM LDOM, 577
	17749	$$CMP^XUSE SIG1, 91
	17750	$$CNV^XLFU TL, 564
	17751	$$CODE2TXT ^XUA4A72, 464
	17752	$$COMCP^XP DUTL, 192
	17753	$$CONVERT^ XLFIPV, 56 7
	17754	$$COS^XLFM TH, 536
	17755	$$COSDEG^X LFMTH, 536
	17756	$$COSH^XLF HYPER, 526
	17757	$$COT^XLFM TH, 537
	17758	$$COTDEG^X LFMTH, 537
	17759	$$COTH^XLF HYPER, 527
	17760	$$CRC16^XL FCRC, 500
	17761	$$CRC32^XL FCRC, 502
	17762	$$CREATE^X USAP, 285
	17763	$$CSC^XLFM TH, 538
	17764	$$CSCDEG^X LFMTH, 538
	17765	$$CSCH^XLF HYPER, 527
	17766	$$CURCP^XP DUTL, 193
	17767	$$CURRSURO ^XQALSURO, 39
	17768	$$DE^XUSES IG1, 92
	17769	$$DEA^XUSE R, 468
	17770	$$DEC^XLFU TL, 565
	17771	$$DECDMS^X LFMTH, 539
	17772	$$DECODE^X THCUTL, 37 7
	17773	$$DECRYP^X USRB1, 294
	17774	$$DEFDIR^% ZISH, 112
	17775	$$DEL^%ZIS H, 113
	17776	$$DELETE^X PDMENU, 21 0
	17777	$$DELETE^X PDPROT, 21 4
	17778	$$DEV^XUTM DEVQ, 312
	17779	$$DMSDEC^X LFMTH, 539
	17780	$$DOW^XLFD T, 503
	17781	$$DT^XLFDT , 504
	17782	$$DTIME^XU P, 465
	17783	$$DTR^XLFM TH, 540
	17784	$$E^XLFMTH , 540
	17785	$$EC^%ZOSV , 96
	17786	$$EN^MXMLD OM, 579
	17787	$$EN^XUA4A 71, 226
	17788	$$EN^XUSES IG1, 92
	17789	$$EN^XUWOR KDY, 229
	17790	$$ENCODE^X THCURL, 37 4
	17791	$$ENCRYP^X USRB1, 295
	17792	$$ESBLOCK^ XUSESIG1, 92
	17793	$$EXP^XLFM TH, 541
	17794	$$FIPS^XIP UTIL, 4
	17795	$$FIPSCHK^ XIPUTIL, 5
	17796	$$FMADD^XL FDT, 505
	17797	$$FMDIFF^X LFDT, 505
	17798	$$FMNAME^X LFNAME, 23 6
	17799	$$FMTE^XLF DT, 506
	17800	$$FMTH^XLF DT, 511
	17801	$$FMTHL7^X LFDT, 511
	17802	$$FORCEIP4 ^XLFIPV, 5 68
	17803	$$FORCEIP6 ^XLFIPV, 5 69
	17804	$$FTG^%ZIS H, 114
	17805	$$GATF^%ZI SH, 115
	17806	$$GET^XPAR , 405
	17807	$$GET^XUA4 A72, 464
	17808	$$GET^XUPA RAM, 280
	17809	$$GET1^DID , 172
	17810	$$GETMASTR ^XTID, 416
	17811	$$GETRPLC^ XTIDTRM, 3 48
	17812	$$GETSTAT^ XTID, 417
	17813	$$GETSURO^ XQALSURO, 39
	17814	$$GETURL^X THC10, 372
	17815	$$GETVUID^ XTID, 419
	17816	$$GTF^%ZIS H, 116
	17817	$$HADD^XLF DT, 512
	17818	$$HANDLE^X USRB4, 295
	17819	$$HDIFF^XL FDT, 512
	17820	$$HL7TFM^X LFDT, 513
	17821	$$HLNAME^X LFNAME, 23 8
	17822	$$HTE^XLFD T, 515
	17823	$$HTFM^XLF DT, 517
	17824	$$ID^XUAF4 , 124
	17825	$$IDX^XUAF 4, 124
	17826	$$IEN^XUAF 4, 125
	17827	$$IEN^XUMF , 134
	17828	$$IEN^XUPS , 45
	17829	$$IEN2CODE ^XUA4A72, 465
	17830	$$INHIBIT^ XUSRB, 292
	17831	$$INSTALDT ^XPDUTL, 1 93
	17832	$$INVERT^X LFSTR, 555
	17833	$$JOB^%ZTL OAD, 336
	17834	$$KCHK^XUS RB, 480
	17835	$$KSP^XUPA RAM, 281
	17836	$$LAST^XPD UTL, 194
	17837	$$LEGACY^X UAF4, 125
	17838	$$LENGTH^X LFMSMT, 55 0
	17839	$$LGR^%ZOS V, 264
	17840	$$LIST^%ZI SH, 116
	17841	$$LJ^XLFST R, 555
	17842	$$LKOPT^XP DMENU, 211
	17843	$$LKPROT^X PDPROT, 21 5
	17844	$$LKUP^XPD KEY, 270
	17845	$$LKUP^XUA F4, 126
	17846	$$LKUP^XUP ARAM, 282
	17847	$$LN^XLFMT H, 541
	17848	$$LOG^XLFM TH, 542
	17849	$$LOOKUP^X USER, 473
	17850	$$LOW^XLFS TR, 556
	17851	$$MADD^XUA F4, 127
	17852	$$MAKEURL^ XTHCURL, 3 75
	17853	$$MAX^XLFM TH, 542
	17854	$$MIN^XLFM TH, 543
	17855	$$MV^%ZISH , 117
	17856	$$NAME^MXM LDOM, 580
	17857	$$NAME^XUA F4, 127
	17858	$$NAME^XUS ER, 475
	17859	$$NAMEFMT^ XLFNAME, 2 41
	17860	$$NEWCP^XP DUTL, 196
	17861	$$NEWERR^% ZTER, 99
	17862	$$NNT^XUAF 4, 128
	17863	$$NODEV^XU TMDEVQ, 31 6
	17864	$$NOW^XLFD T, 517
	17865	$$NPI^XUSN PI, 255
	17866	$$NS^XUAF4 , 128
	17867	$$O99^XUAF 4, 129
	17868	$$OPTDE^XP DUTL, 197
	17869	$$OS^%ZOSV , 265
	17870	$$PADD^XUA F4, 129
	17871	$$PARCP^XP DUTL, 197
	17872	$$PARENT^M XMLDOM, 58 0
	17873	$$PARSEURL ^XTHCURL, 376
	17874	$$PATCH^XP DUTL, 198
	17875	$$PENDING^ XQALBUTL, 18
	17876	$$PI^XLFMT H, 543
	17877	$$PKG^XPDU TL, 198
	17878	$$PKGPAT^X PDIP, 191
	17879	$$PKGPEND^ XQALBUTL, 19
	17880	$$PRNT^XUA F4, 130
	17881	$$PROD^XUP ROD, 283
	17882	$$PRODE^XP DUTL, 199
	17883	$$PROVIDER ^XUSER, 47 6
	17884	$$PSET^%ZT LOAD, 337
	17885	$$PWD^%ZIS H, 119
	17886	$$PWR^XLFM TH, 544
	17887	$$QI^XUSNP I, 256
	17888	$$QQ^XUTMD EVQ, 318
	17889	$$RENAME^X PDKEY, 270
	17890	$$REPEAT^X LFSTR, 557
	17891	$$REPLACE^ XLFSTR, 55 7
	17892	$$REQQ^XUT MDEVQ, 321
	17893	$$RES^XUDH SET, 58
	17894	$$REWIND^% ZIS, 70
	17895	$$RF^XUAF4 , 131
	17896	$$RJ^XLFST R, 558
	17897	$$RPLCLST^ XTIDTRM, 3 49
	17898	$$RPLCMNT^ XTIDTRM, 3 50
	17899	$$RPLCTRL^ XTIDTRM, 3 51
	17900	$$RPLCVALS ^XTIDTRM, 352
	17901	$$RSADECR^ XUSHSH, 51
	17902	$$RSAENCR^ XUSHSH, 52
	17903	$$RT^XUAF4 , 131
	17904	$$RTD^XLFM TH, 544
	17905	$$RTNUP^XP DUTL, 199
	17906	$$S^%ZTLOA D, 343
	17907	$$SCH^XLFD T, 518
	17908	$$SCREEN^X TID, 420
	17909	$$SD^XLFMT H, 545
	17910	$$SDEA^XUS ER, 477
	17911	$$SDETOX^X USER, 471
	17912	$$SEC^XLFD T, 521
	17913	$$SEC^XLFM TH, 545
	17914	$$SECDEG^X LFMTH, 546
	17915	$$SECH^XLF HYPER, 528
	17916	$$SENTENCE ^XLFSTR, 5 59
	17917	$$SETMASTR ^XTID, 422
	17918	$$SETSTAT^ XTID, 353, 423
	17919	$$SETUP1^X QALERT, 31
	17920	$$SETVUID^ XTID, 425
	17921	$$SHAHASH^ XUSHSH, 53
	17922	$$SIBLING^ MXMLDOM, 5 81
	17923	$$SIN^XLFM TH, 546
	17924	$$SINDEG^X LFMTH, 547
	17925	$$SINH^XLF HYPER, 528
	17926	$$SQRT^XLF MTH, 547
	17927	$$STA^XUAF 4, 133
	17928	$$STATUS^% ZISH, 119
	17929	$$STRIP^XL FSTR, 559
	17930	$$SYMENC^M XMLUTL, 58 8
	17931	$$TAN^XLFM TH, 548
	17932	$$TANDEG^X LFMTH, 548
	17933	$$TANH^XLF HYPER, 529
	17934	$$TAXIND^X USTAX, 257
	17935	$$TAXORG^X USTAX, 258
	17936	$$TEMP^XLF MSMT, 551
	17937	$$TEXT^MXM LDOM, 581
	17938	$$TF^XUAF4 , 133
	17939	$$TITLE^XL FSTR, 560
	17940	$$TM^%ZTLO AD, 345
	17941	$$TRIM^XLF STR, 561
	17942	$$TYPE^XPD MENU, 212
	17943	$$TYPE^XPD PROT, 217
	17944	$$TZ^XLFDT , 522
	17945	$$UP^XLFST R, 562
	17946	$$UPCP^XPD UTL, 200
	17947	$$VALIDATE ^XLFIPV, 5 70
	17948	$$VALUE^MX MLDOM, 582
	17949	$$VCD^XLFU TL, 566
	17950	$$VDEA^XUS ER, 479
	17951	$$VER^XPDU TL, 200
	17952	$$VERCP^XP DUTL, 201
	17953	$$VERSION^ %ZOSV, 268
	17954	$$VERSION^ XLFIPV, 57 1
	17955	$$VERSION^ XPDUTL, 20 1
	17956	$$VOLUME^X LFMSMT, 55 2
	17957	$$VPID^XUP S, 45
	17958	$$WEIGHT^X LFMSMT, 55 3
	17959	$$WHAT^XUA F4, 134
	17960	$$WITHIN^X LFDT, 522
	17961	$$WORKDAY^ XUWORKDY, 230
	17962	$$WORKPLUS ^XUWORKDY, 231
	17963	$$XMLHDR^M XMLUTL, 58 8
	17964	%
	17965	%G Utility , 222
	17966	%Index of Routines O ption, 429 , 444
	17967	%RR Routin e, 434
	17968	%RS Routin e, 434
	17969	%ZTPP Util ity, 432
	17970	%ZTRDEL Ro utine, 434
	17971	^
	17972	^ %RR Dire ct Mode Ut ility, 427
	17973	^ %RS Dire ct Mode Ut ility, 428
	17974	^%G (OS-sp ecific)
	17975	Direct Mod e Utility, 222
	17976	^%G Direct Mode Util ity, 221
	17977	^%INDEX Di rect Mode Utility, 4 27, 436
	17978	^%RR Direc t Mode Uti lity, 434
	17979	^%RS Direc t Mode Uti lity, 434
	17980	^%Z Direct Mode Util ity, 427, 432
	17981	^%Z Editor , 222, 224 , 431, 432
	17982	User Inter face, 222
	17983	^%Z Global , 222
	17984	^%ZIS, 58
	17985	^%ZISC, 71
	17986	^%ZOSF
	17987	Global, 25 9
	17988	Nodes, 259
	17989	ACTJ, 260
	17990	AVJ, 260
	17991	BRK, 260
	17992	DEL, 260
	17993	EOFF, 260
	17994	EON, 260
	17995	EOT, 260
	17996	ERRTN, 260
	17997	ETRP, 260
	17998	GD, 260
	17999	GSEL, 260
	18000	JOBPARAM, 260
	18001	LABOFF, 26 0
	18002	LOAD, 260
	18003	LPC, 260
	18004	MAGTAPE, 2 61
	18005	MAXSIZ, 26 1
	18006	MGR, 259, 261
	18007	MTBOT, 261
	18008	MTERR, 261
	18009	MTONLINE, 261
	18010	MTWPROT, 2 61
	18011	NBRK, 261
	18012	NO-PASSALL , 261
	18013	NO-TYPE-AH EAD, 261
	18014	OS, 261
	18015	PASSALL, 2 61
	18016	PRIINQ, 26 1
	18017	PRIORITY, 261
	18018	PROD, 259, 261
	18019	PROGMODE, 261
	18020	RD, 261
	18021	RESJOB, 26 1
	18022	RM, 261
	18023	RSEL, 261
	18024	RSUM, 261
	18025	RSUM1, 262
	18026	SAVE, 262
	18027	SIZE, 262
	18028	SS, 262
	18029	TEST, 262
	18030	TMK, 262
	18031	TRAP, 262
	18032	TRMOFF, 26 2
	18033	TRMON, 262
	18034	TRMRD, 262
	18035	TYPE-AHEAD , 262
	18036	UCI, 262
	18037	UCICHECK, 262
	18038	UPPERCASE, 262
	18039	VOL, 259, 262
	18040	XY, 262
	18041	ZD, 262
	18042	^%ZTBKC Di rect Mode Utility, 2 59
	18043	^%ZTER, 97
	18044	^%ZTER Dir ect Mode U tility, 43 6, 438
	18045	^%ZTLOAD, 304
	18046	^%ZTP1 Dir ect Mode U tility, 42 7
	18047	^%ZTPP Dir ect Mode U tility, 42 7, 432
	18048	^%ZTRDEL D irect Mode Utility, 427, 434
	18049	^nsNTEG Di rect Mode Utility, 4 36
	18050	^XGF Direc t Mode Uti lities, 48 4
	18051	^XGFDEMO D irect Mode Utility, 484
	18052	^XINDEX Di rect Mode Utility, 4 27, 435, 4 36, 444
	18053	^XQ1 Direc t Mode Uti lity, 209
	18054	^XQDATE, 2 27
	18055	^XTEMP Glo bal, 429, 439
	18056	^XTER Dire ct Mode Ut ility, 436 , 438
	18057	^XTERPUR, 438
	18058	^XTERPUR D irect Mode Utility, 436, 438
	18059	^XTFCE Dir ect Mode U tility, 42 7, 431
	18060	^XTFCR Dir ect Mode U tility, 42 7, 431
	18061	^XTMUNIT, 392, 393
	18062	^XTMUNIT1 Routine, 3 92
	18063	^XTMZZUT1 Routine, 3 93
	18064	^XTRCMP Di rect Mode Utility, 4 27, 434
	18065	^XTRGRPE D irect Mode Utility, 427, 431
	18066	^XTVCHG Di rect Mode Utility, 4 27, 432
	18067	^XTVNUM Di rect Mode Utility, 4 27, 432
	18068	^XUP Direc t Mode Uti lity, 276, 438
	18069	^XUP Routi ne, 209
	18070	^XUS Direc t Mode Uti lity, 276
	18071	^XUSCLEAN, 277
	18072	^XUSCLEAN Direct Mod e Utility, 277
	18073	^XUSEC Glo bal, 269
	18074	^XUSESIG, 90
	18075	^XUVERIFY, 296
	18076	^XUWORKDY, 227
	18077	^ZTEDIT Di rect Mode Utility, 2 22
	18078	^ZTMGRSET Direct Mod e Utility, 259
	18079	^ZU Direct Mode Util ity, 277
	18080	A
	18081	Aborting a n Installa tion Durin g the Pre- Install Ro utine (KID S), 171
	18082	Aborting I nstallatio ns During the Enviro nment Chec k (KIDS), 167
	18083	Accessing Questions and Answer s (KIDS), 175
	18084	Acronyms
	18085	Intranet W ebsite, 59 7
	18086	ACTION Men u, 224
	18087	ACTION^XQA LERT, 22
	18088	ACTION^XQH 4, 110
	18089	Actual Usa ge of Alph a/Beta Tes t Options Option, 18 7
	18090	ADD^XPAR, 401
	18091	Adding New Users
	18092	$$ADD^XUSE RNEW, 290
	18093	ADDPAT^XUL MU, 205
	18094	ADDRESS FO R USAGE RE PORTING Fi eld (#22), 185, 188
	18095	Address Hy giene
	18096	$$FIPS^XIP UTIL, 4
	18097	$$FIPSCHK^ XIPUTIL, 5
	18098	APIs, 3
	18099	CCODE^XIPU TIL, 3
	18100	Developer Tools, 3
	18101	POSTAL^XIP UTIL, 5
	18102	POSTALB^XI PUTIL, 8
	18103	Advanced B uild Techn iques (KID S), 165
	18104	AHISTORY^X QALBUTL, 1 3
	18105	AK.Keyname Cross-ref erence, 26 9
	18106	ALERT File (#8992), 10, 12, 23 , 28, 32, 37, 43, 59 2
	18107	Alert Iden tifier, 11
	18108	ALERT TRAC KING File (#8992.1), 11, 13, 1 4, 15, 21, 22, 25, 3 2
	18109	ALERTDAT^X QALBUTL, 1 5
	18110	Alerts
	18111	$$CURRSURO ^XQALSURO, 39
	18112	$$GETSURO^ XQALSURO, 39
	18113	$$PENDING^ XQALBUTL, 18
	18114	$$PKGPEND^ XQALBUTL, 19
	18115	$$SETUP1^X QALERT, 31
	18116	ACTION^XQA LERT, 22
	18117	AHISTORY^X QALBUTL, 1 3
	18118	Alert Iden tifier, 11
	18119	ALERTDAT^X QALBUTL, 1 5
	18120	APIs, 13
	18121	DELETE^XQA LERT, 23, 24
	18122	DELSTAT^XQ ALBUTL, 16
	18123	Developer Tools
	18124	Overview, 10
	18125	FORWARD^XQ ALFWD, 37
	18126	GETACT^XQA LERT, 25
	18127	Glossary, 12
	18128	NOTIPURG^X QALBUTL, 1 7
	18129	Package Id entifier, 11
	18130	PATIENT^XQ ALERT, 26
	18131	PTPURG^XQA LBUTL, 20
	18132	RECIPURG^X QALBUTL, 2 0
	18133	REMVSURO^X QALSURO, 4 0
	18134	SETSURO1^X QALSURO, 4 1
	18135	SETUP^XQAL ERT, 27
	18136	SUROFOR^XQ ALSURO, 42
	18137	SUROLIST^X QALSURO, 4 3
	18138	USER^XQALE RT, 36
	18139	USERDATA^X QALBUTL, 2 1
	18140	USERLIST^X QALBUTL, 2 2
	18141	ALERTS Fil e (#8992), 33
	18142	ALPHA,BETA TEST OPTI ON Multipl e Field (# 33), 184, 189
	18143	Alpha/Beta Test Opti on Usage M enu, 187
	18144	ALPHA/BETA TEST PACK AGE Multip le Field ( #32), 184, 189
	18145	ALPHA/BETA TESTING F ield (#20) , 185, 189
	18146	Alpha/Beta Tracking
	18147	Initiating (KIDS), 1 85
	18148	Build Entr y, 185
	18149	Local Opti on Countin g, 184
	18150	Monitoring (KIDS), 1 87
	18151	Purging of the Optio n Counts, 188
	18152	Send Alpha /Beta Usag e to Progr ammers Opt ion, 188
	18153	Sending a Summary Me ssage, 186 , 188
	18154	Terminatin g (KIDS), 188
	18155	Terminatin g Tracking
	18156	Local Test Software Option Usa ge, 189
	18157	National R elease Sof tware Opti on Usage, 189
	18158	Usage Repo rts (KIDS) , 187
	18159	Alpha/Beta Tracking (KIDS), 18 4
	18160	Analyzing Routines
	18161	Routine To ols, 429
	18162	APIs, 202
	18163	CHKLOCAL^X DRMERG2, 3 70
	18164	Document O bject Mode l (DOM), 5 73
	18165	LKUP^XTLKM GR, 381
	18166	Lock Manag er
	18167	Housekeepi ng, 202
	18168	M Unit, 39 3
	18169	Obsolete
	18170	XRT0 Outpu t Paramete r, Start T ime, 266
	18171	XRTN Input Parameter , Routine Name, 268
	18172	APP PROXY ALLOWED Fi eld (#.11) , 285
	18173	Appending Text to a Server Req uest Bulle tin or Mai lman Reply , 274
	18174	Applicatio n Programm ing Interf ace (API)
	18175	Address Hy giene, 3
	18176	Alerts, 13
	18177	Common Ser vices, 45
	18178	Data Secur ity, 48
	18179	DEA ePCS U tility, 46 8, 471, 47 7, 479
	18180	Device Han dler, 55
	18181	DNS, 88
	18182	Electronic Signature s, 90
	18183	Error Proc essing, 96
	18184	Field Moni toring, 10 1
	18185	Help Proce ssor, 109
	18186	Host Files , 111
	18187	Institutio n File, 12 1
	18188	KIDS, 190
	18189	Menu Manag er, 210
	18190	Miscellane ous, 225
	18191	Name Stand ardization , 232
	18192	National P rovider Id entifier ( NPI), 254
	18193	Operating System, 25 9
	18194	Security K eys, 269
	18195	Signon/Sec urity, 280
	18196	Spooling, 300
	18197	TaskMan, 3 12
	18198	Toolkit, 3 46
	18199	Unwinder, 461
	18200	User, 464
	18201	XGF Functi on Library , 485
	18202	XLF Functi on Library , 500
	18203	XML, 576
	18204	Applicatio n Programm ing Interf aces (APIs ), 202
	18205	M Unit, 39 3
	18206	Applicatio n Proxy Us er, 285, 2 86
	18207	Ask if Pro duction Ac count Opti on, 283
	18208	Ask Instal lation Que stions, Ho w to (KIDS ), 174
	18209	Assumption s, lxiv
	18210	AUTO MENU, 208
	18211	AVHLPTXT^X US2, 284
	18212	B
	18213	BLDLST^XPA REDIT, 410
	18214	BMES^XPDUT L, 192
	18215	Build Entr ies (KIDS) , 143
	18216	BUILD File (#9.6), 1 43, 148, 1 66, 170, 1 72, 181, 1 85, 188, 1 89, 198, 2 00, 429, 4 33, 439
	18217	Build Name (KIDS), 1 48
	18218	Build Scre ens (KIDS) , 146
	18219	C
	18220	Calculate and Show C hecksum Va lues Optio n
	18221	Programmer Options M enu, 437, 438
	18222	CALL^%ZIST CP, 79
	18223	Callable E ntry Point s
	18224	XTLKKWL, 3 81
	18225	Calling
	18226	^%ZTLOAD t o Create T asks (Task Man), 301
	18227	^%ZTLOAD w ithin a Ta sk (TaskMa n), 307
	18228	Device Han dler (^%ZI S) within a Task (Ta skMan), 30 7
	18229	EN^XUTMDEV Q to Creat e Tasks (T askMan), 3 02
	18230	Callout Bo xes, lxii
	18231	CAN DELETE WITHOUT P ROCESSING Field (#.1 ), 28, 32
	18232	Candidate Collection , Selectin g Fields t o Compare in, 360
	18233	Capacity M anagement
	18234	Response T ime Measur es (Obsole te)
	18235	APIs
	18236	XRT0 Outpu t Paramete r, Start T ime, 266
	18237	XRTN Input Parameter , Routine Name, 268
	18238	Capacity P lanning
	18239	National D atabase, 2 65
	18240	CCODE^XIPU TIL, 3
	18241	CDSYS^XUAF 4, 121
	18242	CHCKSUM^XT SUMBLD Dir ect Mode U tility, 43 5, 437, 43 8
	18243	CHECK^XTSU MBLD Routi ne, 433, 4 35, 438
	18244	CHECK1^XTS UMBLD Rout ine, 433, 435, 438
	18245	Checking
	18246	For Backgr ound Execu tion
	18247	ZTQUEUED ( TaskMan), 306
	18248	For Stop R equests (T askMan), 3 04
	18249	Checkpoint Parameter Node, 178
	18250	Checkpoint s with Cal lbacks, 17 7
	18251	Checkpoint s without Callbacks (Data Stor age), 180
	18252	CHECKSUM R EPORT Fiel d, 433
	18253	CHECKSUM V ALUE Field , 433
	18254	Checksums, 224, 434, 437
	18255	CHG^XPAR, 402
	18256	CHGA^XGF, 485
	18257	child node , 586
	18258	CHILDREN^X UAF4, 122
	18259	CHKLOCAL^X DRMERG2 AP I, 370
	18260	Choosing W hat Data t o Send wit h a File ( KIDS), 152
	18261	Clean Erro r Trap Opt ion, 96
	18262	CLEAN^XGF, 486
	18263	CLEANUP^XU LMU, 202
	18264	CLEAR^XGF, 487
	18265	CLOSE^%ZIS H, 112
	18266	CLOSE^%ZIS TCP, 80
	18267	CLOSE^%ZIS UTL, 81
	18268	CLOSEST PR INTER Fiel d, 65
	18269	CMNT^MXMLD OM, 578
	18270	Common Ser vices
	18271	$$IEN^XUPS , 45
	18272	$$VPID^XUP S, 45
	18273	APIs, 45
	18274	Developer Tools, 45
	18275	EN1^XUPSQR Y, 46
	18276	Compare lo cal/nation al checksu ms report Option, 43 3, 438
	18277	Compare Ro utines on Tape to Di sk Option, 433
	18278	Compare Tw o Routines Option, 4 34
	18279	Comparing Routines
	18280	Routine To ols, 433
	18281	Conformanc e Error, 5 76
	18282	Conforming XML, 575
	18283	Contents, xxii
	18284	Controllin g
	18285	The Disabl e Options/ Protocols Prompt (KI DS), 168
	18286	The Move R outines to Other CPU s Prompt ( KIDS), 169
	18287	The Queuei ng of the Install Pr ompt (KIDS ), 168
	18288	Convert
	18289	$H to Exte rnal Forma t, 515
	18290	$H to VA F ileMan Dat e Format, 517
	18291	$H/VA File Man date t o Seconds, 521
	18292	Another Ba se to Base 10, 565
	18293	Base 10 to Another B ase, 564
	18294	Between Tw o Bases, 5 63
	18295	Decimals t o Degrees: Minutes:Se conds, 539
	18296	Degrees to Radians, 540
	18297	Degrees:Mi nutes:Seco nds to Dec imal, 539
	18298	Domain Nam e to IP Ad dresses, 8 8
	18299	HL7 Date t o VA FileM an Date, 5 13
	18300	HL7 Format ted Name t o Name, 23 6
	18301	Length Mea surement, 550
	18302	Name to HL 7 Formatte d Name, 23 8
	18303	Radians to Degrees, 544
	18304	Seconds to $H, 503
	18305	String to Lowercase, 556
	18306	String to Soundex, 2 26
	18307	String to Uppercase, 562
	18308	Temperatur e Measurem ent, 551
	18309	VA FileMan Date to $ H, 511
	18310	VA FileMan Date to E xternal Fo rmat, 506
	18311	VA FileMan Date to H L7 Date, 5 11
	18312	Volume Mea surement, 552
	18313	Weight Mea surement, 553
	18314	Copy Build to Build (KIDS), 14 5
	18315	COUNTY COD E File (#5 .13), 6, 8
	18316	CRC Functi ons
	18317	$$CRC16^XL FCRC, 500
	18318	$$CRC32^XL FCRC, 502
	18319	CRC Functi ons (XLF), 500
	18320	Create a B uild Using Namespace (KIDS), 1 44
	18321	Creating
	18322	Tasks Usin g Schedule d Options (TaskMan), 302
	18323	Creating a Package-s pecific Us er Termina tion Actio n, 279
	18324	Creating B uilds (KID S), 143
	18325	Creating O ptions, 20 7
	18326	Creating T ransport G lobals tha t Install Efficientl y (KIDS), 164
	18327	Customized Merge, 35 6
	18328	Customizin g a Server Request B ulletin, 2 74
	18329	CVC^XUSRB, 292
	18330	D
	18331	Data Dicti onary
	18332	Data Dicti onary Util ities Menu , lxiv
	18333	Listings, lxiv
	18334	Data Dicti onary Clea nup (KIDS) , 155
	18335	Data Dicti onary Upda te (KIDS), 148
	18336	Data Secur ity
	18337	$$AESDECR^ XUSHSH, 48
	18338	$$AESENCR^ XUSHSH, 49
	18339	$$B64DECD^ XUSHSH, 50
	18340	$$B64ENCD^ XUSHSH, 50
	18341	$$RSADECR^ XUSHSH, 51
	18342	$$RSAENCR^ XUSHSH, 52
	18343	$$SHAHASH^ XUSHSH, 53
	18344	APIs, 48
	18345	Data Stand ardization
	18346	Replacemen t Relation ships, 347
	18347	Toolkit AP Is, 346
	18348	Databases
	18349	Capacity P lanning Na tional Dat abase, 265
	18350	Date Funct ions
	18351	$$$H^XLFDT , 503
	18352	$$DOW^XLFD T, 503
	18353	$$DT^XLFDT , 504
	18354	$$FMADD^XL FDT, 505
	18355	$$FMDIFF^X LFDT, 505
	18356	$$FMTE^XLF DT, 506
	18357	$$FMTH^XLF DT, 511
	18358	$$FMTHL7^X LFDT, 511
	18359	$$HADD^XLF DT, 512
	18360	$$HDIFF^XL FDT, 512
	18361	$$HL7TFM^X LFDT, 513
	18362	$$HTE^XLFD T, 515
	18363	$$HTFM^XLF DT, 517
	18364	$$NOW^XLFD T, 517
	18365	$$SCH^XLFD T, 518
	18366	$$SEC^XLFD T, 521
	18367	$$TZ^XLFDT , 522
	18368	$$WITHIN^X LFDT, 522
	18369	Date Funct ions (XLF) , 503
	18370	Dates
	18371	Miscellane ous Develo per Tools, 227
	18372	DAYS FOR B ACKUP REVI EWER Field (#.15), 3 3
	18373	DE^XUSHSHP , 93
	18374	DEA eCPS U tility
	18375	$$DEA^XUSE R, 468
	18376	$$SDEA^XUS ER, 477
	18377	$$SDETOX^X USER, 471
	18378	$$VDEA^XUS ER, 479
	18379	DEA ePCS U tility
	18380	APIs, 468, 471, 477, 479
	18381	DEFAULT TI MED READ ( SECONDS) F ield (#210 ), 466
	18382	DEL^XPAR, 402
	18383	DEL^XPDKEY , 269
	18384	DELCOMP^XL FNAME2, 25 0
	18385	Delete a R outine or Skip Insta lling (KID S), 167
	18386	Delete Old (>14d) Al erts Optio n, 29, 33
	18387	Delete Rou tines Opti on, 434
	18388	Delete Unr eferenced Options Op tion, 221
	18389	DELETE^MXM LDOM, 578
	18390	DELETE^XQA LERT, 23
	18391	DELETEA^XQ ALERT, 24
	18392	Deleting
	18393	Routines
	18394	Routine To ols, 434
	18395	DELSTAT^XQ ALBUTL, 16
	18396	DESC^%ZTLO AD, 333
	18397	Determinin g How Data is Instal led at the Receiving Site (KID S), 153
	18398	Developer Tools
	18399	^XINDEX Di rect Mode Utility, 4 35
	18400	Address Hy giene, 3
	18401	Alerts
	18402	Overview, 10
	18403	Common Ser vices, 45
	18404	Device Han dler
	18405	Overview, 55
	18406	Domain Nam e Service (DNS), 88
	18407	Electronic Signature s, 90
	18408	Error Proc essing, 96
	18409	Field Moni toring, 10 1
	18410	File Acces s Security
	18411	Overview, 106
	18412	Help Proce ssor, 109
	18413	Host Files , 111
	18414	Institutio n File, 12 1
	18415	KIDS, 142
	18416	M Unit
	18417	Overview, 392
	18418	Menu Manag er, 207
	18419	Miscellane ous, 221
	18420	Date Conve rsions and Calculati ons, 227
	18421	Lookup Uti lity, 226
	18422	Progress B ar Emulato r, 225
	18423	Name Stand ardization , 232
	18424	National P rovider Id entifier ( NPI), 254
	18425	Operating System Int erface
	18426	Overview, 259
	18427	Security K eys
	18428	Overview, 269
	18429	Server Opt ions, 273
	18430	Signon/Sec urity
	18431	Overview, 276
	18432	Spooling
	18433	Overview, 299
	18434	TaskMan
	18435	Overview, 301
	18436	Toolkit, 3 46
	18437	Unwinder, 461
	18438	User, 464
	18439	XGF Functi on Library
	18440	Overview, 483
	18441	XLF Functi on Library
	18442	Overview, 500
	18443	XML, 576
	18444	DEVICE Fil e (#3.5), 38, 59, 60 , 61, 62, 64, 65, 66 , 70, 111, 400, 465, 466
	18445	Device Han dler
	18446	$$RES^XUDH SET, 58
	18447	$$REWIND^% ZIS, 70
	18448	$I, 62
	18449	^%ZIS, 58
	18450	^%ZISC, 71
	18451	APIs, 55
	18452	CALL^%ZIST CP, 79
	18453	CLOSE^%ZIS TCP, 80
	18454	CLOSE^%ZIS UTL, 81
	18455	Developer Tools
	18456	Overview, 55
	18457	Device Typ e, 65
	18458	DEVICE^XUD HGUI, 55
	18459	ENDR^%ZISS , 73
	18460	ENS^%ZISS, 74
	18461	GKILL^%ZIS S, 78
	18462	GSET^%ZISS , 78
	18463	Help Frame s, 68, 69
	18464	HLP1^%ZIS, 68
	18465	HLP2^%ZIS, 69
	18466	HOME^%ZIS, 69
	18467	KILL^%ZISS , 79
	18468	Multiple D evices and ^%ZIS, 68
	18469	OPEN^%ZISU TL, 81
	18470	PKILL^%ZIS P, 71
	18471	RMDEV^%ZIS UTL, 83
	18472	SAVDEV^%ZI SUTL, 84
	18473	Subtype, 6 4
	18474	USE^%ZISUT L, 84
	18475	DEVICE^XUD HGUI, 55
	18476	Devices
	18477	Rewinding, 70
	18478	DI DDU Men u, lxiv
	18479	Dialog Ent ries (KIDS ), 159
	18480	DIALOG Fil e (#.84), 159, 404
	18481	DIFROM, 14 3, 150, 16 5, 171, 17 3
	18482	DIFROM Var iable, 166 , 172
	18483	DILIST Opt ion, lxiv
	18484	DINUM, 355 , 356, 370 , 371
	18485	Direct Mod e Utilitie s
	18486	^%G, 221
	18487	^%G (OS-sp ecific), 2 22
	18488	^%INDEX, 4 36
	18489	^%ZTER, 43 6
	18490	^nsNTEG, 4 36
	18491	^XGF, 484
	18492	^XGFDEMO, 484
	18493	^XINDEX, 4 35, 436
	18494	^XTER, 96, 436
	18495	^XTERPUR, 96, 436
	18496	^XTLKKWL, 381
	18497	^XUSCLEAN, 277
	18498	^ZTEDIT, 2 22
	18499	^ZTMB, 311
	18500	^ZTMCHK, 3 11
	18501	^ZTMGRSET, 259
	18502	^ZTMON, 31 1
	18503	^ZU, 277
	18504	CHCKSUM^XT SUMBLD, 43 5, 437, 43 8
	18505	Check Envi ronment (T askMan), 3 11
	18506	Error Proc essing, 96
	18507	H^XUS, 277
	18508	Menu Manag er, 209
	18509	^XQ1, 209
	18510	Miscellane ous Progra mmer
	18511	^%ZTER, 43 8
	18512	^XUP, 438
	18513	Monitor Ta skMan, 311
	18514	ONE^nsNTEG , 436
	18515	Operating System Int erface, 25 9
	18516	^%ZTBKC, 2 59
	18517	Global Blo ck Count, 259
	18518	Update ^%Z OSF Nodes, 259
	18519	Place Task man in a W AIT State, 311
	18520	Remove Tas kman from WAIT State Option, 3 11
	18521	Restart Ta skMan, 311
	18522	RESTART^ZT M, 311
	18523	Routine To ols
	18524	^ %RR (OS- specific), 427
	18525	^ %RS (OS- specific), 428
	18526	^%INDEX, 4 27
	18527	^%RR (OS-s pecific), 434
	18528	^%RS (OS-s pecific), 434
	18529	^%Z, 427, 432
	18530	^%ZTP1, 42 7
	18531	^%ZTPP, 42 7, 432
	18532	^%ZTRDEL, 427, 434
	18533	^XINDEX, 4 27, 444
	18534	^XTFCE, 42 7, 431
	18535	^XTFCR, 42 7, 431
	18536	^XTRCMP, 4 27, 434
	18537	^XTRGRPE, 427, 431
	18538	^XTVCHG, 4 27, 432
	18539	^XTVNUM, 4 27, 432
	18540	TE^XTRCMP, 427, 433
	18541	RUN^ZTMKU, 311
	18542	Signon/Sec urity, 276
	18543	^XUP, 276
	18544	^XUS, 276
	18545	^XUSCLEAN, 277
	18546	^ZU, 277
	18547	H^XUS, 277
	18548	Starting T askMan, 31 1
	18549	STOP^ZTMKU , 311
	18550	Stopping T askMan, 31 1
	18551	TaskMan, 3 11
	18552	Toolkit
	18553	Miscellane ous Tools, 221
	18554	Routine To ols, 427
	18555	Verificati on Tools, 435
	18556	Verificati on Tools
	18557	^%ZTER, 43 8
	18558	^XTER, 438
	18559	^XTERPUR, 438
	18560	^XTTER, 43 8
	18561	WAIT^ZTMKU , 311
	18562	XGF Functi on Library
	18563	^XGFDEMO, 484
	18564	Direct Mod e Utility
	18565	RUNSET^XTM UNIT(setna me), 392
	18566	DISABLE, 1 68
	18567	Disclaimer s
	18568	Documentat ion, lxi
	18569	Software, lx
	18570	Discontinu ation
	18571	USER TERMI NATE ROUTI NE, 279
	18572	DISP^XQORM 1, 463
	18573	DISP^XUTMO PT, 322
	18574	DIV4^XUSER , 472
	18575	DIVGET^XUS RB2, 481
	18576	DIVSET^XUS RB2, 481
	18577	DK^XTLKMGR , 383
	18578	DLAYGO
	18579	^DIC Calls , 107
	18580	^DIE Calls , 107
	18581	When Navig ating to F iles, 106
	18582	DLL^XTLKMG R, 383
	18583	DNS
	18584	APIs, 88
	18585	DNS IP Fie ld (#8989. 3,51), 88
	18586	Document O bject Mode l (DOM), 5 73, 587
	18587	Document T ype Defini tion, 574, 575
	18588	Documentat ion
	18589	Symbols, l xi
	18590	Documentat ion Conven tions, lxi
	18591	Documentat ion Discla imer, lxi
	18592	Documentat ion Naviga tion, lxii i
	18593	Documents
	18594	XML, 586
	18595	DOLRO^%ZOS V, 263
	18596	Domain, 28 1
	18597	DOMAIN Fil e (#4.2), 281, 400
	18598	Domain Nam e Service (DNS)
	18599	$$ADDRESS^ XLFNSLK, 8 8
	18600	Developer Tools, 88
	18601	MAIL^XLFNS LK, 89
	18602	DQ^%ZTLOAD , 334
	18603	DSD^ZISPL, 300
	18604	DSDOC^ZISP L, 300
	18605	DSH^XTLKMG R, 384
	18606	DSY^XTLKMG R, 384
	18607	DUPLICATE RECORD fil e, 356
	18608	DUPLICATE RECORD Fil e (#15), 3 55, 357, 3 58, 359, 3 62
	18609	Duplicate Record Mer ge
	18610	Toolkit AP Is, 355
	18611	DUPLICATE RESOLUTION File (#15 ), 362
	18612	DUPLICATE RESOLUTION File (#15 .1), 355, 358, 360
	18613	Duplicate Resolution Utilities , 358
	18614	Candidate Collection , Selectin g Fields t o Compare in, 360
	18615	Customized Merge, 35 6
	18616	DUPLICATE RECORD fil e, 356
	18617	DUPLICATE RECORD fil e (#15), 3 62
	18618	DUPLICATE RECORD Fil e (#15), 3 57
	18619	DUPLICATE RESOLUTION file, 358
	18620	DUPLICATE RESOLUTION file (#15 ), 362
	18621	DUPLICATE RESOLUTION File (#15 .1), 360
	18622	Duplicate Threshold% , 362
	18623	Merge Capa bility
	18624	Developing , 356
	18625	POTENTIAL DUPLICATE THRESHOLD% , 362
	18626	Potential Duplicates , 362
	18627	Selecting Fields to Compare in Candidate Collectio n, 360
	18628	Duplicate Test Routi nes
	18629	Examples, 366
	18630	Duplicate Threshold% , 362
	18631	DUZ(”AG”), , 276
	18632	DUZ(0), 10 6
	18633	DUZ(2), 27 6
	18634	E
	18635	Edit a Bui ld
	18636	Components
	18637	Dialog ent ries, 159
	18638	Forms, 159
	18639	Options, 1 57
	18640	Protocols, 157
	18641	Routines, 158
	18642	Templates, 160
	18643	Components (KIDS), 1 56
	18644	File List
	18645	Data Dicti onary Upda te (KIDS), 148
	18646	DD (Full o r Partial) (KIDS), 1 50
	18647	Sending Se curity Cod es (KIDS), 149
	18648	Files (KID S), 148
	18649	Name & Ver sion, Buil d Informat ion (KIDS) , 147
	18650	Edit a Bui ld (KIDS), 146
	18651	Edit a Bui ld—Screen 4 (KIDS), 174
	18652	EDIT HISTO RY Multipl e, 223
	18653	Edit Optio ns, 207
	18654	EDIT^XPARE DIT, 410
	18655	EDIT^XUTMO PT, 323
	18656	Editing in Line Mode
	18657	Help, 223
	18658	Editing Ro utines
	18659	Routine To ols, 431
	18660	Editors
	18661	^%Z, 222, 224, 431, 432
	18662	User Inter face, 222
	18663	EDITPAR^XP AREDIT, 41 0
	18664	Electronic Signature s
	18665	$$CHKSUM^X USESIG1, 9 1
	18666	$$CMP^XUSE SIG1, 91
	18667	$$DE^XUSES IG1, 92
	18668	$$EN^XUSES IG1, 92
	18669	$$ESBLOCK^ XUSESIG1, 92
	18670	^XUSESIG, 90
	18671	APIs, 90
	18672	DE^XUSHSHP , 93
	18673	Developer Tools, 90
	18674	EN^XUSHSHP , 94
	18675	HASH^XUSHS HP, 94
	18676	SIG^XUSEIG , 90
	18677	EN^MXMLPRS E, 583
	18678	EN^XDRMERG , 368
	18679	EN^XPAR, 4 03
	18680	EN^XPAREDI T, 411
	18681	EN^XPDIJ, 191
	18682	EN^XQH, 10 9
	18683	EN^XQOR, 4 61
	18684	EN^XQORM, 462
	18685	EN^XUSHSHP , 94
	18686	EN^XUTMDEV Q, 314
	18687	EN^XUTMTP, 324
	18688	EN1^XQH, 1 09
	18689	EN1^XQOR, 461
	18690	EN1^XUPSQR Y, 46
	18691	ENDR^%ZISS , 73
	18692	ENS^%ZISS, 74
	18693	Enter/Edit Kernel Si te Paramet ers Option , 189
	18694	Entity
	18695	Parameter Tools
	18696	Toolkit AP Is, 400
	18697	Entity Cat alog, 574
	18698	VA FileMan -compatibl e database , 573
	18699	Entry Acti on Options , 208
	18700	Entry and Exit Execu te Stateme nts, 109
	18701	ENVAL^XPAR , 404
	18702	Environmen t Check is Run Twice (KIDS), 1 65
	18703	Environmen t Check Ro utine (KID S), 165
	18704	Error
	18705	Log, 438
	18706	ERROR LOG File (#3.0 75), 97
	18707	ERROR MESS AGES File (#3.076), 97
	18708	Error Proc essing
	18709	$$NEWERR^% ZTER, 99
	18710	^%ZTER, 97
	18711	^XTER, 96
	18712	^XTERPUR, 96
	18713	APIs, 96
	18714	Developer Tools, 96
	18715	Direct Mod e Utilitie s, 96
	18716	UNWIND^%ZT ER, 100
	18717	Error Trap Display O ption, 96
	18718	Errors
	18719	Conformanc e, 576
	18720	Log, 438
	18721	Processing Kernel Er ror Trappi ng and Rep orting, 43 8
	18722	Reporting, 438
	18723	Tracking A lpha/Beta Software E rrors (KID S), 186
	18724	Trapping, 438
	18725	Errors Log ged in Alp ha/Beta Te st (QUEUED ) Option, 185, 186
	18726	EVE Menu, 142
	18727	Event Type s
	18728	VistA XML Parser
	18729	CHARACTERS , 585
	18730	COMMENT, 5 85
	18731	DOCTYPE, 5 84
	18732	ENDDOCUMEN T, 584
	18733	ENDELEMENT , 585
	18734	ERROR, 586
	18735	EXTERNAL, 585
	18736	PI, 585
	18737	STARTDOCUM ENT, 584
	18738	STARTELEME NT, 585
	18739	Event Type s recogniz ed by Vist A XML Pars er
	18740	NOTATION, 585
	18741	Event-driv en Interfa ce, 573
	18742	Examples
	18743	XML Parser
	18744	Usage, 586
	18745	Exit Actio n Options, 208
	18746	EXIT^XPDID , 226
	18747	Exporting Globals (K IDS), 163
	18748	External D ocument Ty pe Definit ion, 574, 575
	18749	External E ntities, 5 74, 575
	18750	F
	18751	F4^XUAF4, 123
	18752	Field Leve l Protecti on, 106
	18753	Field Moni toring
	18754	APIs, 101
	18755	Developer Tools, 101
	18756	OPKG^XUHUI , 101
	18757	Fields
	18758	ADDRESS FO R USAGE RE PORTING (# 22), 185, 188
	18759	ALPHA,BETA TEST OPTI ON Multipl e (#33), 1 84, 189
	18760	ALPHA/BETA TEST PACK AGE Multip le (#32), 184, 189
	18761	ALPHA/BETA TESTING ( #20), 185, 189
	18762	APP PROXY ALLOWED (# .11), 285
	18763	CAN DELETE WITHOUT P ROCESSING (#.1), 28, 32
	18764	CHECKSUM R EPORT, 433
	18765	CHECKSUM V ALUE, 433
	18766	CLOSEST PR INTER, 65
	18767	DAYS FOR B ACKUP REVI EWER (#.15 ), 33
	18768	DEFAULT TI MED READ ( SECONDS) ( #210), 466
	18769	DNS IP (#8 989.3,51), 88
	18770	EDIT HISTO RY Multipl e, 223
	18771	INSTALLATI ON MESSAGE (#21), 18 5
	18772	MASTER ENT RY FOR VUI D, 415, 41 6, 422, 42 3
	18773	OPEN PARAM ETERS, 60, 64
	18774	PACKAGE FI LE LINK, 1 82, 183
	18775	PACKAGE NA MESPACE OR PREFIX (# 23), 185
	18776	PATCH APPL ICATION HI STORY (#11 05, Multip le), 191
	18777	PRE-TRANSP ORTATION R OUTINE f(# 900), 170
	18778	Protection , 106
	18779	STATION NU MBER (#99) , 133, 135
	18780	SURROGATE END DATE/T IME (#.04) , 43
	18781	SURROGATE FOR ALERTS (#.02), 4 3
	18782	SURROGATE START DATE /TIME (#.0 3), 43
	18783	TIME ZONE (#1), 522
	18784	TIMED READ (# OF SEC ONDS) (#20 0.1), 466
	18785	TIMED READ (# OF SEC ONDS) (#51 .1), 466
	18786	TRANSPORT BUILD NUMB ER (#63), 433
	18787	TYPE (#4), 212
	18788	USE PARAME TERS, 64
	18789	USER CLASS (#9.5), 2 85
	18790	USER TERMI NATE ROUTI NE, 279
	18791	USER TERMI NATE TAG, 279
	18792	VERSION (# 22, Multip le), 191
	18793	Figures, l iii
	18794	File Acces s
	18795	FTG^%ZISH, 575
	18796	File Acces s Security
	18797	Developer Tools
	18798	Overview, 106
	18799	DLAYGO
	18800	^DIC Calls , 107
	18801	^DIE Calls , 107
	18802	When Navig ating to F iles, 106
	18803	Field Leve l Protecti on, 106
	18804	File Navig ation, 106
	18805	File Merge Capabilit y
	18806	Developing , 356
	18807	File Navig ation, 106
	18808	FileMan, 5 73
	18809	Files
	18810	ALERT (#89 92), 10, 1 2, 23, 28, 32, 37, 4 3, 592
	18811	ALERT TRAC KING (#899 2.1), 11, 13, 14, 15 , 21, 22, 25, 32
	18812	ALERTS(#89 92), 33
	18813	BUILD (#9. 6), 143, 1 48, 166, 1 70, 172, 1 81, 185, 1 88, 189, 1 98, 200, 4 29, 433, 4 39
	18814	COUNTY COD E (#5.13), 6, 8
	18815	DEVICE (#3 .5), 400
	18816	DEVICE (#3 .5), 38, 5 9, 60, 61, 62, 64, 6 5, 66, 70, 111
	18817	DEVICE (#3 .5), 465
	18818	DEVICE (#3 .5), 466
	18819	DIALOG (#. 84), 159, 404
	18820	DOMAIN (#4 .2), 281, 400
	18821	DUPLICATE RECORD (#1 5), 355, 3 57, 358, 3 59, 362
	18822	DUPLICATE RESOLUTION (#15), 36 2
	18823	DUPLICATE RESOLUTION (#15.1), 355, 358, 360
	18824	ERROR LOG (#3.075), 97
	18825	ERROR MESS AGES (#3.0 76), 97
	18826	FORUM ROUT INE (#9.8) , 433
	18827	HELP FRAME (#9.2), 1 09, 110
	18828	HL7 MESSAG E TEXT (#7 72), 135
	18829	HOLIDAY (# 40.5), 227 , 229, 230 , 231
	18830	HOSPITAL L OCATION (# 44), 400
	18831	ICD DIAGNO SIS (#80), 386
	18832	ICD OPERAT ION/PROCED URE (#80.1 ), 386
	18833	INDEX (#.1 1), 251
	18834	INSTALL (# 9.7), 190, 191, 192, 195, 196, 197, 200, 429, 439
	18835	INSTITUTIO N (#4), 12 1, 122, 12 3, 124, 12 5, 126, 12 7, 128, 12 9, 130, 13 1, 133, 13 4, 135, 25 5, 258, 28 1, 400, 47 2
	18836	INSTITUTIO N ASSOCIAT ION TYPES (#4.05), 1 30, 132
	18837	KERMIT HOL DING (#898 0), 378
	18838	KERNEL PAR AMETERS (# 8989.2), 2 80, 282
	18839	KERNEL SYS TEM PARAME TERS (#898 9.3), 88, 112, 184, 189, 281, 290, 466
	18840	LOCAL KEYW ORD (#8984 .1), 382, 383, 385
	18841	LOCAL LOOK UP (#8984. 4), 381, 3 82, 383, 3 84, 385, 3 86, 387, 3 91
	18842	LOCAL SHOR TCUT (#898 4.2), 382, 384, 390
	18843	LOCAL SYNO NYM (#8984 .3), 382, 384, 386, 391
	18844	MAILMAN SI TE PARAMET ERS (#4.3) , 522
	18845	MAILMAN TI ME ZONE (# 4.4), 514, 522
	18846	MERGE IMAG E (#15.4), 368, 371
	18847	MUMPS OPER ATING SYST EM (#.7), 154
	18848	MUNIT TEST GROUP (#8 992.8), 39 2
	18849	NAME COMPO NENTS (#20 ), 233, 23 8, 240, 24 1, 245, 25 1, 252, 25 3
	18850	NAME COMPO NENTS File (#20), 23 2, 250
	18851	NEW PERSON (#200), 1 8, 19, 20, 21, 37, 3 9, 40, 41, 42, 43, 4 5, 46, 90, 92, 93, 9 4, 101, 10 2, 233, 24 0, 245, 25 1, 255, 25 7, 269, 27 7, 279, 28 0, 285, 28 6, 290, 40 0, 464, 46 5, 466, 46 7, 468, 46 9, 472, 47 3, 475, 47 6
	18852	OE/RR LIST (#100.21) , 400
	18853	OPTION (#1 9), 101, 1 57, 184, 2 07, 208, 2 09, 211, 2 12, 218, 2 22, 278, 2 89, 302, 3 22, 323, 3 24, 461
	18854	OPTION SCH EDULING (# 19.2), 157 , 301, 302 , 303, 323
	18855	PACKAGE (# 9.4), 143, 174, 181, 182, 183, 191, 201, 279, 355, 357, 358, 400, 429, 439
	18856	PARAMETER DEFINITION (#8989.51 ), 401, 40 3, 405, 41 0, 412
	18857	PARAMETER ENTITY (#8 989.518), 400
	18858	PARAMETER TEMPLATE ( #8989.52), 401, 412, 413
	18859	PARAMETERS (#8989.5) , 401, 403
	18860	PATIENT (# 2), 11, 20 , 26, 205, 206
	18861	PERSON CLA SS (#8932. 1), 464, 4 65
	18862	PROTOCOL ( #101), 101 , 137, 213 , 214, 215 , 216, 217 , 461, 462 , 595
	18863	REMOTE PRO CEDURE (#8 994), 285
	18864	ROOM-BED ( #405.4), 4 00
	18865	ROUTINE (# 9.8), 158, 223, 433, 434
	18866	SECURITY K EY (#19.1) , 269
	18867	SERVICE/SE CTION (#49 ), 33, 400
	18868	SIGN-ON LO G (#3.081) , 277
	18869	SPOOL DATA (#3.519), 300
	18870	SPOOL DOCU MENT (#3.5 1), 300
	18871	STATE (#5) , 3, 6, 8
	18872	TASK SYNC FLAG (#14. 8), 310, 3 11
	18873	TASKS (#14 .4), 304, 305, 334
	18874	TEAM (#404 .51), 400
	18875	TERMINAL T YPE (#3.2) , 60, 64, 72, 73, 74
	18876	USER CLASS (#201), 2 85
	18877	USR CLASS (#8930), 4 00
	18878	VOLUME SET (#14.5), 335
	18879	XDR REPOIN TED ENTRY (#15.3), 3 68
	18880	XML ENTITY CATALOG ( #950), 574
	18881	XQAB ERROR S LOGGED ( #8991.5), 185
	18882	XTV ROUTIN E CHANGES (#8991), 4 37
	18883	XTV ROUTIN E CHANGES File (#899 1), 437
	18884	FIND^XPDPR OT, 214
	18885	Flow Chart Entire Ro utine Opti on, 431
	18886	Flow Chart from Entr y Point Op tion, 431
	18887	Forced Que uing, 67
	18888	Form Feeds , 64, 71
	18889	Forms (KID S), 159
	18890	FORUM ROUT INE File ( #9.8), 433
	18891	FORWARD^XQ ALFWD, 37
	18892	FRAME^XGF, 488
	18893	FTG^%ZISH
	18894	Read File into M Glo bal, 575
	18895	FTP Protoc ol, 575
	18896	Full DD (A ll Fields) (KIDS), 1 50
	18897	Functions
	18898	FTG^%ZISH, 575
	18899	G
	18900	GETACT^XQA LERT, 25
	18901	GETENT^XPA REDIT, 411
	18902	GETENV^%ZO SV, 264
	18903	GETIREF^XT ID, 414
	18904	GETLST^XPA R, 406
	18905	GETPAR^XPA REDIT, 412
	18906	GETPEER^%Z OSV, 298
	18907	GETWP^XPAR , 407
	18908	GKILL^%ZIS S, 78
	18909	Global
	18910	^%Z, 222
	18911	Global Blo ck Count o ption, 259
	18912	Global Blo ck Count O ption, 221
	18913	Globals
	18914	^%ZOSF, 25 9
	18915	^%ZRTL
	18916	Obsolete, 267, 268
	18917	^XTEMP Glo bal, 429, 439
	18918	^XTV, 184
	18919	^XUSEC, 26 9, 270
	18920	Block Coun t, 259
	18921	XTMP, 160, 161, 168, 263, 264, 295, 296, 307
	18922	XUTL, 463
	18923	Glossary, 592
	18924	Alerts, 12
	18925	Intranet W ebsite, 59 7
	18926	Group Rout ine Edit O ption, 431 , 432
	18927	GSET^%ZISS , 78
	18928	H
	18929	H^XUS, 277 , 283
	18930	H^XUS Dire ct Mode Ut ility, 277
	18931	HASH^XUSHS HP, 94
	18932	Header Opt ions, 208
	18933	Help
	18934	At Prompts , lxiv
	18935	Line Mode Editing, 2 23
	18936	Online, lx iv
	18937	Question M arks, lxiv
	18938	HELP FRAME File (#9. 2), 109, 1 10
	18939	Help proce ssor
	18940	ACTION^XQH 4, 110
	18941	EN^XQH, 10 9
	18942	EN1^XQH, 1 09
	18943	Help Proce ssor
	18944	APIs, 109
	18945	Developer Tools, 109
	18946	Entry and Exit Execu te Stateme nts, 109
	18947	History, R evisions t o Document ation and Patches, i i
	18948	HL7 MESSAG E TEXT Fil e (#772), 135
	18949	HLP1^%ZIS, 68
	18950	HLP2^%ZIS, 69
	18951	HOLIDAY Fi le (#40.5) , 227, 229 , 230, 231
	18952	Home Pages
	18953	Acronyms I ntranet We bsite, 597
	18954	Adobe Webs ite, lxiv
	18955	EPMO Websi te, lxi
	18956	Glossary I ntranet We bsite, 597
	18957	Kernel Web site, lxiv
	18958	VA Softwar e Document Library ( VDL), lxiv
	18959	HOME^%ZIS, 69
	18960	HOSPITAL L OCATION Fi le (#44), 400
	18961	Host Files
	18962	$$DEFDIR^% ZISH, 112
	18963	$$DEL^%ZIS H, 113
	18964	$$FTG^%ZIS H, 114
	18965	$$GATF^%ZI SH, 115
	18966	$$GTF^%ZIS H, 116
	18967	$$LIST^%ZI SH, 116
	18968	$$MV^%ZISH , 117
	18969	$$PWD^%ZIS H, 119
	18970	$$STATUS^% ZISH, 119
	18971	APIs, 111
	18972	CLOSE^%ZIS H, 112
	18973	Developer Tools, 111
	18974	OPEN^%ZISH , 118
	18975	How KIDS M atches Inc oming Entr ies with E xisting En tries, 154
	18976	How to
	18977	Ask Instal lation Que stions (KI DS), 174
	18978	Obtain Tec hnical Inf ormation O nline, lxi ii
	18979	Override M TLU, 381
	18980	Use this M anual, lx
	18981	Write Code to Queue Tasks, 301
	18982	HTTP Clien t
	18983	Toolkit AP Is, 371
	18984	HTTP Proto col, 575
	18985	Hyperbolic Trigonome tric Funct ions
	18986	$$ACOSH^XL FHYPER, 52 3
	18987	$$ACOTH^XL FHYPER, 52 4
	18988	$$ACSCH^XL FHYPER, 52 4
	18989	$$ASECH^XL FHYPER, 52 5
	18990	$$ASINH^XL FHYPER, 52 5
	18991	$$ATANH^XL FHYPER, 52 6
	18992	$$COSH^XLF HYPER, 526
	18993	$$COTH^XLF HYPER, 527
	18994	$$CSCH^XLF HYPER, 527
	18995	$$SECH^XLF HYPER, 528
	18996	$$SINH^XLF HYPER, 528
	18997	$$TANH^XLF HYPER, 529
	18998	Hyperbolic Trigonome tric Funct ions (XLF) , 523
	18999	I
	19000	ICD DIAGNO SIS File ( #80), 386
	19001	ICD OPERAT ION/PROCED URE File ( #80.1), 38 6
	19002	IEN
	19003	Duplicate Record Mer ge Utiliti es, 360
	19004	INDEX File (#.11), 2 51
	19005	INIT^XPDID , 225
	19006	Initiating
	19007	Alpha/Beta Tracking (KIDS), 18 5
	19008	Build Entr y, 185
	19009	INITKB^XGF , 489
	19010	Input Rout ines Optio n, 434
	19011	INSTALL Fi le (#9.7), 190, 191, 192, 195, 196, 197, 200, 429, 439
	19012	Install Pa ckage(s) O ption, 165
	19013	INSTALLATI ON MESSAGE Field (#2 1), 185
	19014	Instance
	19015	Parameter Tools
	19016	Toolkit AP Is, 401
	19017	Institutio n, 281
	19018	INSTITUTIO N ASSOCIAT ION TYPES File (#4.0 5), 130, 1 32
	19019	Institutio n File
	19020	$$ACTIVE^X UAF4, 121
	19021	$$CIRN^XUA F4, 122
	19022	$$ID^XUAF4 , 124
	19023	$$IDX^XUAF 4, 124
	19024	$$IEN^XUAF 4, 125
	19025	$$IEN^XUMF , 134
	19026	$$LEGACY^X UAF4, 125
	19027	$$LKUP^XUA F4, 126
	19028	$$MADD^XUA F4, 127
	19029	$$NAME^XUA F4, 127
	19030	$$NNT^XUAF 4, 128
	19031	$$NS^XUAF4 , 128
	19032	$$O99^XUAF 4, 129
	19033	$$PADD^XUA F4, 129
	19034	$$PRNT^XUA F4, 130
	19035	$$RF^XUAF4 , 131
	19036	$$RT^XUAF4 , 131
	19037	$$STA^XUAF 4, 133
	19038	$$TF^XUAF4 , 133
	19039	$$WHAT^XUA F4, 134
	19040	APIs, 121
	19041	CDSYS^XUAF 4, 121
	19042	CHILDREN^X UAF4, 122
	19043	Developer Tools, 121
	19044	F4^XUAF4, 123
	19045	LOOKUP^XUA F4, 126
	19046	MAIN^XUMFI , 135
	19047	MAIN^XUMFP , 136
	19048	PARENT^XUA F4, 130
	19049	SIBLING^XU AF4, 132
	19050	INSTITUTIO N File (#4 ), 121, 12 2, 123, 12 4, 125, 12 6, 127, 12 8, 129, 13 0, 131, 13 3, 134, 13 5, 255, 25 8, 281, 40 0, 472
	19051	Intended A udience, l x
	19052	INTRO^XUSR B, 293
	19053	Introducti on, 1
	19054	IOXY^XGF, 489
	19055	IP Address Functions
	19056	$$CONVERT^ XLFIPV, 56 7
	19057	$$FORCEIP4 ^XLFIPV, 5 68
	19058	$$FORCEIP6 ^XLFIPV, 5 69
	19059	$$VALIDATE ^XLFIPV, 5 70
	19060	$$VERSION^ XLFIPV, 57 1
	19061	IP Address Functions (XLF), 56 7
	19062	ISQED^%ZTL OAD, 334
	19063	K
	19064	K^XTLKMGR, 385
	19065	KERMIT
	19066	Toolkit AP Is, 378
	19067	KERMIT HOL DING File (#8980), 3 78
	19068	Kernel
	19069	Error Trap ping and R eporting, 438
	19070	Website, l xiv
	19071	Kernel Ins tallation & Distribu tion Syste m Menu, 14 2
	19072	Kernel Man agement Me nu, 189, 2 83
	19073	KERNEL PAR AMETERS Fi le (#8989. 2), 280, 2 82
	19074	KERNEL SYS TEM PARAME TERS File (#8989.3), 88, 112, 184, 189, 281, 290, 466
	19075	Key
	19076	Parameters
	19077	KIDS, 172
	19078	Variables
	19079	KIDS, 172
	19080	Key Lookup , 269
	19081	Key Variab les
	19082	KIDS, 166
	19083	Server Opt ions, 273
	19084	Tasks, 303
	19085	KIDS
	19086	$$PKG^XPDU TL, 198
	19087	$$PKGPAT^X PDIP, 191
	19088	$$VER^XPDU TL, 200
	19089	$$VERSION^ XPDUTL, 20 1
	19090	Alpha/Beta Tracking, 184
	19091	APIs, 190
	19092	Build Entr ies, 143
	19093	Build Name , 148
	19094	Build Scre ens, 146
	19095	Checkpoint Parameter Node, 178
	19096	Checkpoint s with Cal lbacks, 17 7
	19097	Checkpoint s without Callbacks (Data Stor age), 180
	19098	Choosing W hat Data t o Send wit h a File, 152
	19099	Copy Build to Build, 145
	19100	Create a B uild Using Namespace , 144
	19101	Creating B uilds, 143
	19102	Data Dicti onary Clea nup, 155
	19103	Data Dicti onary Upda te, 148
	19104	Determinin g How Data is Instal led at the Receiving Site, 153
	19105	Developer Tools, 142
	19106	Advanced B uild Techn iques, 165
	19107	Edit a Bui ld, 146
	19108	Components , 156
	19109	Dialog Ent ries, 159
	19110	File List
	19111	DD (Full o r Partial) , 150
	19112	Files, 148
	19113	Forms, 159
	19114	Name & Ver sion, Buil d Informat ion, 147
	19115	Options an d Protocol s, 157
	19116	Routines, 158
	19117	Templates, 160
	19118	Edit a Bui ld—Screen 4, 174
	19119	EN^XPDIJ, 191
	19120	Environmen t Check, 1 65
	19121	$$PATCH^XP DUTL, 198
	19122	$$RTNUP^XP DUTL, 199
	19123	Aborting I nstallatio ns, 167
	19124	DIFROM Var iable, 166
	19125	DISABLE Sc heduled Op tions, Opt ions, and Protocols Prompt, 16 8
	19126	Key Variab les, 166
	19127	Move routi nes to oth er CPUs Pr ompt, 169
	19128	Queueing t he Install Prompt, 1 68
	19129	Routine In stall Opti ons, 167
	19130	Run Twice, 165
	19131	Sample Rou tine, 170
	19132	Self-Conta ined Routi ne, 165
	19133	Verifying Patch Inst allation, 167
	19134	Version Nu mbers, 167
	19135	XPDENV Var iable, 166
	19136	XPDNM Vari able, 166
	19137	XPDNM(”SEQ ”), 166, 1 72
	19138	XPDNM(”TST ”), 166, 1 72
	19139	Exporting Globals, 1 63
	19140	Full DD (A ll Fields) , 150
	19141	How KIDS M atches Inc oming Entr ies with E xisting En tries, 154
	19142	How to Ask Installat ion Questi ons, 174
	19143	Initiating Alpha/Bet a Tracking , 185
	19144	Build Entr y, 185
	19145	Installati on Questio ns
	19146	M Code, 17 5
	19147	Questions and answer s, 175
	19148	Skipping, 175
	19149	Subscripts , 175
	19150	Where Aske d, 176
	19151	Limited Re solution o f Pointers , 155
	19152	M Code in Questions, 175
	19153	Monitoring Alpha/Bet a Tracking , 187
	19154	Multi-Pack age Builds , 163
	19155	NEW the DI FROM Varia ble When C alling Mai lMan, 173
	19156	Options, 1 42
	19157	Package Fi le Link, 1 82
	19158	Partial DD (Some Fie lds), 150
	19159	File Numbe r Level, 1 50
	19160	Multiple L evel, 150
	19161	Pre- and P ost-Instal l
	19162	Aborting i nstallatio ns, 171
	19163	Pre- and P ost-Instal l Routines
	19164	$$COMCP^XP DUTL, 192
	19165	$$CURCP^XP DUTL, 193
	19166	$$LAST^XPD UTL, 194
	19167	$$NEWCP^XP DUTL, 196
	19168	$$OPTDE^XP DUTL, 197
	19169	$$PARCP^XP DUTL, 197
	19170	$$PRODE^XP DUTL, 199
	19171	$$UPCP^XPD UTL, 200
	19172	$$VERCP^XP DUTL, 201
	19173	BMES^XPDUT L, 192
	19174	Checkpoint Parameter Node, 178
	19175	Checkpoint s without Callbacks, 180
	19176	DIFROM Var iable, 172
	19177	Key
	19178	Parameters , 172
	19179	Variables, 172
	19180	MES^XPDUTL , 195
	19181	Sample Rou tine, 179
	19182	XPDNM Vari able, 172
	19183	ZTQUEUED V ariable, 1 73
	19184	Pre- and P ost-Instal l Routines :Special F eatures, 1 71
	19185	PRE-TRANSP ORTATION R OUTINE Fie ld (#900), 170
	19186	Question S ubscripts, 175
	19187	Re-Indexin g Files, 1 55
	19188	Required B uild, 181
	19189	Return All Install D ates/Times
	19190	$$CURCP^IN STALDT, 19 3
	19191	Send Alpha /Beta Usag e to Progr ammers Opt ion, 188
	19192	Sending Se curity Cod es, 149
	19193	Setting a File’s Pac kage Revis ion Data N ode (Post- Install), 172
	19194	Skipping I nstallatio n Question s, 175
	19195	Terminatin g Alpha/Be ta Trackin g, 188
	19196	Local Test Software Option Usa ge, 189
	19197	National R elease Sof tware Opti on Usage, 189
	19198	Track Pack age Nation ally, 183
	19199	Tracking A lpha/Beta Software E rrors, 186
	19200	Transporti ng a distr ibution
	19201	Efficient builds, 16 4
	19202	Transporti ng a Distr ibution, 1 60
	19203	Update the Status Ba r During P re- and Po st-Install Routines, 173
	19204	UPDATE^XPD ID, 190
	19205	Usage Repo rts for Al pha/Beta T racking, 1 87
	19206	Using Chec kpoints (P re- and Po st-Install Routines) , 176
	19207	When to Tr ansport Mo re than On e Transpor t Global i n a Distri bution, 16 2
	19208	Where Ques tions Are Asked Duri ng Install ations, 17 6
	19209	KILL^%ZISS , 79
	19210	KILL^%ZTLO AD, 304, 3 05, 336
	19211	KILL^XUSCL EAN, 289
	19212	Known issu es
	19213	ASCII char acter subs et, 575
	19214	Known Issu es
	19215	Enforcing Whitespace , 576
	19216	Entity Sub stitutions , 575
	19217	File Acces s, 575
	19218	FTG^%ZISH
	19219	Parser Ope ration, 57 5
	19220	FTP Protoc ol, 575
	19221	HTTP Proto col, 575
	19222	KWIC Cross -reference , 381, 382
	19223	L
	19224	L^XTLKMGR, 385
	19225	Limited Re solution o f Pointers (KIDS), 1 55
	19226	Line Mode Editing He lp, 223
	19227	Link
	19228	Package Fi le Link, 1 82
	19229	List File Attributes Option, l xiv
	19230	List Globa l Option, 222
	19231	List Routi nes Option , 432
	19232	LKUP^XTLKM GR, 386
	19233	LKUP^XTLKM GR API, 38 1
	19234	Load Routi nes, 434
	19235	Load/refre sh checksu m values i nto ROUTIN E file Opt ion, 434
	19236	LOCAL KEYW ORD File ( #8984.1), 382, 383, 385
	19237	LOCAL LOOK UP File (# 8984.4), 3 81, 382, 3 83, 384, 3 85, 386, 3 87, 391
	19238	LOCAL SHOR TCUT File (#8984.2), 382, 384, 390
	19239	LOCAL SYNO NYM File ( #8984.3), 382, 384, 386, 391
	19240	Lock Manag er
	19241	ADDPAT^XUL MU, 205
	19242	APIs
	19243	Lock Dicti onary, 205
	19244	CLEANUP^XU LMU, 202
	19245	Housekeepi ng
	19246	APIs, 202
	19247	Lock Dicti onary
	19248	APIs, 205
	19249	PAT^XULMU, 205
	19250	SETCLEAN^X ULMU, 203
	19251	UNCLEAN^XU LMU, 204
	19252	Lock Templ ate, 206
	19253	LOGOUT^XUS RB, 293
	19254	LOGRSRC^%Z OSV, 264
	19255	Logs
	19256	Error Log, 438
	19257	Long Runni ng Tasks
	19258	Writing Tw o-step Tas ks (TaskMa n), 307, 3 08
	19259	Lookup Uti lity
	19260	Miscellane ous Develo per Tools, 226
	19261	LOOKUP^XUA F4, 126
	19262	Low Usage of Alpha/B eta Test O ptions Opt ion, 188
	19263	Lowercase
	19264	$$LOW^XLFS TR, 556
	19265	M
	19266	M Code in Questions (KIDS), 17 5
	19267	M Unit
	19268	APIs, 393
	19269	Developer Tools
	19270	Overview, 392
	19271	MAIL^XLFNS LK, 89
	19272	MAILMAN SI TE PARAMET ERS File ( #4.3), 522
	19273	MAILMAN TI ME ZONE Fi le (#4.4), 514, 522
	19274	MAIN^XUMFI , 135
	19275	MAIN^XUMFP , 136
	19276	MASTER ENT RY FOR VUI D Field, 4 15, 416, 4 22, 423
	19277	Math Funct ions
	19278	$$ABS^XLFM TH, 529
	19279	$$ACOS^XLF MTH, 530
	19280	$$ACOSDEG^ XLFMTH, 53 0
	19281	$$ACOT^XLF MTH, 531
	19282	$$ACOTDEG^ XLFMTH, 53 1
	19283	$$ACSC^XLF MTH, 532
	19284	$$ACSCDEG^ XLFMTH, 53 2
	19285	$$ASEC^XLF MTH, 533
	19286	$$ASECDEG^ XLFMTH, 53 3
	19287	$$ASIN^XLF MTH, 534
	19288	$$ASINDEG^ XLFMTH, 53 4
	19289	$$ATAN^XLF MTH, 535
	19290	$$ATANDEG^ XLFMTH, 53 5
	19291	$$COS^XLFM TH, 536
	19292	$$COSDEG^X LFMTH, 536
	19293	$$COT^XLFM TH, 537
	19294	$$COTDEG^X LFMTH, 537
	19295	$$CSC^XLFM TH, 538
	19296	$$CSCDEG^X LFMTH, 538
	19297	$$DECDMS^X LFMTH, 539
	19298	$$DMSDEC^X LFMTH, 539
	19299	$$DTR^XLFM TH, 540
	19300	$$E^XLFMTH , 540
	19301	$$EXP^XLFM TH, 541
	19302	$$LN^XLFMT H, 541
	19303	$$LOG^XLFM TH, 542
	19304	$$MAX^XLFM TH, 542
	19305	$$MIN^XLFM TH, 543
	19306	$$PI^XLFMT H, 543
	19307	$$PWR^XLFM TH, 544
	19308	$$RTD^XLFM TH, 544
	19309	$$SD^XLFMT H, 545
	19310	$$SEC^XLFM TH, 545
	19311	$$SECDEG^X LFMTH, 546
	19312	$$SIN^XLFM TH, 546
	19313	$$SINDEG^X LFMTH, 547
	19314	$$SQRT^XLF MTH, 547
	19315	$$TAN^XLFM TH, 548
	19316	$$TANDEG^X LFMTH, 548
	19317	Math Funct ions (XLF) , 529
	19318	Measuremen t Function s
	19319	$$BSA^XLFM SMT, 549
	19320	$$LENGTH^X LFMSMT, 55 0
	19321	$$TEMP^XLF MSMT, 551
	19322	$$VOLUME^X LFMSMT, 55 2
	19323	$$WEIGHT^X LFMSMT, 55 3
	19324	Measuremen t Function s (XLF), 5 49
	19325	Menu Manag er
	19326	$$ACCESS^X QCHK, 218
	19327	$$ADD^XPDM ENU, 210
	19328	$$ADD^XPDP ROT, 213
	19329	$$DELETE^X PDMENU, 21 0
	19330	$$DELETE^X PDPROT, 21 4
	19331	$$LKOPT^XP DMENU, 211
	19332	$$LKPROT^X PDPROT, 21 5
	19333	$$TYPE^XPD MENU, 212
	19334	$$TYPE^XPD PROT, 217
	19335	APIs, 210
	19336	Creating O ptions, 20 7
	19337	Developer Tools, 207
	19338	Direct Mod e Utilitie s, 209
	19339	^XQ1, 209
	19340	FIND^XPDPR OT, 214
	19341	NEXT^XQ92, 218
	19342	OP^XQCHK, 219
	19343	Option Typ es, 207
	19344	OUT^XPDMEN U, 211
	19345	OUT^XPDPRO T, 215
	19346	RENAME^XPD MENU, 212
	19347	RENAME^XPD PROT, 216
	19348	Variables for Develo per Use, 2 08
	19349	XQ1, 209
	19350	XQMM(”A”) Variable, 208
	19351	XQMM(”B”) Variable, 208
	19352	XQMM(”J”) Variable, 209
	19353	XQMM(”N”) Variable, 209
	19354	XQUIT Vari able, 208
	19355	Menus
	19356	ACTION, 22 4
	19357	Alpha/Beta Test Opti on Usage M enu, 187
	19358	Data Dicti onary Util ities, lxi v
	19359	DI DDU, lx iv
	19360	EVE, 142
	19361	Kernel Ins tallation & Distribu tion Syste m, 142
	19362	Kernel Man agement Me nu, 189, 2 83
	19363	Operations Managemen t, 187
	19364	Programmer Options, 142, 221, 222, 428, 435, 437, 444
	19365	Routine To ols, 428, 444
	19366	Systems Ma nager Menu , 142, 436
	19367	Verifier T ools, 436
	19368	Verifier T ools Menu, 436
	19369	XPD MAIN, 142
	19370	XQAB MENU, 187
	19371	XTV MENU M enu, 436
	19372	XUKERNEL, 189, 283
	19373	XUPROG, 14 2, 428, 43 7, 444
	19374	XUPR-ROUTI NE-TOOLS, 428, 444
	19375	XUSITEMGR, 187
	19376	ZTMQUEUABL E OPTIONS, 186
	19377	Merge Capa bility
	19378	Duplicate Resolution Utilities
	19379	Developing , 356
	19380	MERGE IMAG E File (#1 5.4), 368, 371
	19381	MES^XPDUTL , 195
	19382	Miscellane ous
	19383	$$EN^XUA4A 71, 226
	19384	$$EN^XUWOR KDY, 229
	19385	$$WORKDAY^ XUWORKDY, 230
	19386	$$WORKPLUS ^XUWORKDY, 231
	19387	^XQDATE, 2 27
	19388	^XUWORKDY, 227
	19389	APIs, 225
	19390	Developer Tools, 221
	19391	Date Conve rsions and Calculati ons, 227
	19392	Lookup Uti lity, 226
	19393	Progress B ar Emulato r, 225
	19394	Direct Mod e Utilitie s, 221
	19395	EXIT^XPDID , 226
	19396	INIT^XPDID , 225
	19397	TITLE^XPDI D, 225
	19398	Miscellane ous Progra mmer Tools
	19399	^%Z Editor , 222
	19400	Delete Unr eferenced Options Op tion, 221
	19401	Global Blo ck Count O ption, 221
	19402	List Globa l Option, 222
	19403	Test an op tion not i n your men u Option, 222
	19404	Miscellane ous Tools
	19405	^%G Direct Mode Util ity, 221
	19406	Monitor Ta skman Opti on, 311
	19407	Monitoring
	19408	Alpha/Beta Tracking (KIDS), 18 7
	19409	Move routi nes to oth er CPUs Pr ompt (KIDS ), 169
	19410	MSG^XQOR, 462
	19411	Multi-Pack age Builds (KIDS), 1 63
	19412	Multi-Term Look-Up ( MTLU)
	19413	Callable E ntry Point
	19414	XTLKKWL, 3 81
	19415	Direct Mod e Utilitie s
	19416	^XTLKKWL, 381
	19417	How to Ove rride, 381
	19418	LOCAL LOOK UP File (# 8984.4), 3 81
	19419	MTLU and V A FileMan lookups, 3 81
	19420	MTLU and V A FileMan Supported Calls, 381
	19421	MTLU, How to Overrid e
	19422	VA FileMan lookups a nd MTLU, 3 81
	19423	Supported Calls, 381
	19424	Toolkit AP Is, 381
	19425	VA FileMan Supported Calls, 38 1
	19426	MUMPS OPER ATING SYST EM File (# .7), 154
	19427	MUnit Test Group edi t Option, 392
	19428	MUNIT TEST GROUP Fil e (#8992.8 ), 392
	19429	MXMLDOM
	19430	$$ATTRIB^M XMLDOM, 57 6
	19431	$$CHILD^MX MLDOM, 577
	19432	$$CMNT^MXM LDOM, 577
	19433	$$EN^MXMLD OM, 579
	19434	$$NAME^MXM LDOM, 580
	19435	$$PARENT^M XMLDOM, 58 0
	19436	$$SIBLING^ MXMLDOM, 5 81
	19437	$$TEXT^MXM LDOM, 581
	19438	$$VALUE^MX MLDOM, 582
	19439	CMNT^MXMLD OM, 578
	19440	DELETE^MXM LDOM, 578
	19441	EN^MXMLPRS E, 583
	19442	TEXT^MXMLD OM, 582
	19443	MXMLDOM Ro utine, 574 , 576
	19444	MXMLUTL
	19445	$$SYMENC^M XMLUTL, 58 8
	19446	$$XMLHDR^M XMLUTL, 58 8
	19447	N
	19448	NAME COMPO NENTS File (#20), 23 2, 233, 23 8, 240, 24 1, 245, 25 0, 251, 25 2, 253
	19449	Name Stand ardization
	19450	$$BLDNAME^ XLFNAME, 2 32
	19451	$$CLEANC^X LFNAME, 23 4
	19452	$$FMNAME^X LFNAME, 23 6
	19453	$$HLNAME^X LFNAME, 23 8
	19454	$$NAMEFMT^ XLFNAME, 2 41
	19455	APIs, 232
	19456	DELCOMP^XL FNAME2, 25 0
	19457	Developer Tools, 232
	19458	NAMECOMP^X LFNAME, 24 0
	19459	STDNAME^XL FNAME, 245
	19460	UPDCOMP^XL FNAME2, 25 1
	19461	NAMECOMP^X LFNAME, 24 0
	19462	Namespaces
	19463	XU, 187
	19464	National D atabase
	19465	Capacity P lanning, 2 65
	19466	National P rovider Id entifier ( NPI)
	19467	$$CHKDGT^X USNPI, 254
	19468	$$NPI^XUSN PI, 255
	19469	$$QI^XUSNP I, 256
	19470	$$TAXIND^X USTAX, 257
	19471	$$TAXORG^X USTAX, 258
	19472	APIs, 254
	19473	Developer Tools, 254
	19474	Navigation
	19475	DLAYGO, 10 6
	19476	Files, 106
	19477	NDEL^XPAR, 408
	19478	NEW PERSON File (#20 0), 18, 19 , 20, 21, 37, 39, 40 , 41, 42, 43, 45, 46 , 90, 92, 93, 94, 10 1, 102, 23 3, 240, 24 5, 251, 25 5, 257, 26 9, 277, 27 9, 280, 28 5, 286, 29 0, 400, 46 4, 465, 46 6, 467, 46 8, 469, 47 2, 473, 47 5, 476
	19479	NEW the DI FROM Varia ble When C alling Mai lMan (KIDS ), 173
	19480	NEXT^XQ92, 218
	19481	Nodes
	19482	^%ZOSF, 25 9
	19483	ACTJ, 260
	19484	AVJ, 260
	19485	BRK, 260
	19486	DEL, 260
	19487	EOFF, 260
	19488	EOT, 260
	19489	ERRTN, 260
	19490	ETRP, 260
	19491	GSEL, 260
	19492	JOBPARAM, 260
	19493	LABOFF, 26 0
	19494	LOAD, 260
	19495	LPC, 260
	19496	MAGTAPE, 2 61
	19497	MAXSIZ, 26 1
	19498	MGR, 259, 261
	19499	MTBOT, 261
	19500	MTERR, 261
	19501	MTONLINE, 261
	19502	MTWPROT, 2 61
	19503	NBRK, 261
	19504	NO-PASSALL , 261
	19505	NO-TYPE-AH EAD, 261
	19506	OS, 261
	19507	PASSALL, 2 61
	19508	PRIINQ, 26 1
	19509	PRIORITY, 261
	19510	PROD, 259, 261
	19511	PROGMODE, 261
	19512	RD, 261
	19513	RESJOB, 26 1
	19514	RM, 261
	19515	RSEL, 261
	19516	RSUM, 261
	19517	RSUM1, 262
	19518	SAVE, 262
	19519	SIZE, 262
	19520	SS, 262
	19521	TEST, 262
	19522	TMK, 262
	19523	TRAP, 262
	19524	TRMOFF, 26 2
	19525	TRMON, 262
	19526	TRMRD, 262
	19527	UCI, 262
	19528	UCICHECK, 262
	19529	UPPERCASE, 262
	19530	VOL, 259, 262
	19531	XY, 262
	19532	ZD, 262
	19533	Non-confor ming XML, 575
	19534	NOTIPURG^X QALBUTL, 1 7
	19535	Number of Workdays C alculation , 229
	19536	O
	19537	Obsolete
	19538	$$NEWERR^% ZTER, 99
	19539	^XQDATE, 2 27
	19540	^XUWORKDY, 227
	19541	D H^XUS, 2 77
	19542	T0^%ZOSV, 266
	19543	T1^%ZOSV, 267
	19544	USER TERMI NATE ROUTI NE Option, 279
	19545	Obtaining
	19546	Data Dicti onary List ings, lxiv
	19547	OE/RR LIST File (#10 0.21), 400
	19548	ONE^nsNTEG Direct Mo de Utility , 436
	19549	Online
	19550	Documentat ion, lxiv
	19551	Technical Informatio n, How to Obtain, lx iii
	19552	OP^XQCHK, 219
	19553	OPEN PARAM ETERS Fiel d, 60, 64
	19554	OPEN^%ZISH , 118
	19555	OPEN^%ZISU TL, 81
	19556	Operating System
	19557	APIs, 259
	19558	Operating System Int erface
	19559	$$ACTJ^%ZO SV, 262
	19560	$$AVJ^%ZOS V, 263
	19561	$$EC^%ZOSV , 96
	19562	$$LGR^%ZOS V, 264
	19563	$$OS^%ZOSV , 265
	19564	$$VERSION^ %ZOSV, 268
	19565	Developer Tools
	19566	Overview, 259
	19567	Direct Mod e Utilitie s, 259
	19568	DOLRO^%ZOS V, 263
	19569	GETENV^%ZO SV, 264
	19570	Global Blo ck Count, 259
	19571	LOGRSRC^%Z OSV, 264
	19572	SETENV^%ZO SV, 265
	19573	SETNM^%ZOS V, 266
	19574	T0^%ZOSV, 266
	19575	T1^%ZOSV, 267
	19576	Update ^%Z OSF Nodes, 259
	19577	Operations Managemen t Menu, 18 7
	19578	OPKG^XUHUI , 101
	19579	OPTION Fil e (#19), 1 01, 157, 1 84, 207, 2 08, 209, 2 11, 212, 2 18, 222, 2 78, 289, 3 02, 322, 3 23, 324, 4 61
	19580	Entry Acti on, 208
	19581	Exit Actio n, 208
	19582	Header, 20 8
	19583	OPTION SCH EDULING Fi le (#19.2) , 157, 301 , 302, 303 , 323
	19584	OPTION^%ZT LOAD, 337
	19585	Options
	19586	%Index of Routines, 429, 444
	19587	ACTION, 22 4
	19588	Actual Usa ge of Alph a/Beta Tes t Options, 187
	19589	Alpha/Beta Test Opti on Usage M enu, 187
	19590	Ask if Pro duction Ac count Opti on, 283
	19591	Calculate and Show C hecksum Va lues
	19592	Programmer Options M enu, 437, 438
	19593	Clean Erro r Trap, 96
	19594	Compare lo cal/nation al checksu ms report, 433, 438
	19595	Compare Ro utines on Tape to Di sk, 433
	19596	Compare Tw o Routines , 434
	19597	Creating, 207
	19598	Data Dicti onary Util ities, lxi v
	19599	Delete Old (>14d) Al erts, 29, 33
	19600	Delete Rou tines, 434
	19601	Delete Unr eferenced Options, 2 21
	19602	DI DDU, lx iv
	19603	DILIST, lx iv
	19604	Enter/Edit Kernel Si te Paramet ers option , 189
	19605	Error Trap Display O ption, 96
	19606	Errors Log ged in Alp ha/Beta Te st (QUEUED ), 185, 18 6
	19607	EVE, 142
	19608	Flow Chart Entire Ro utine, 431
	19609	Flow Chart from Entr y Point, 4 31
	19610	Global Blo ck Count, 221, 259
	19611	Group Rout ine Edit, 431, 432
	19612	Input Rout ines, 434
	19613	Install Pa ckage(s), 165
	19614	Kernel Ins tallation & Distribu tion Syste m, 142
	19615	Kernel Man agement Me nu, 189, 2 83
	19616	KIDS, 142, 157
	19617	List File Attributes , lxiv
	19618	List Globa l, 222
	19619	List Routi nes, 432
	19620	Load/refre sh checksu m values i nto ROUTIN E file, 43 4
	19621	Low Usage of Alpha/B eta Test O ptions, 18 8
	19622	Monitor Ta skman, 311
	19623	MUnit Test Group edi t, 392
	19624	Operations Managemen t, 187
	19625	Output Rou tines, 434
	19626	Place Task man in a W AIT State, 311
	19627	Print Alph a/Beta Err ors (Date/ Site/Num/R ou/Err), 1 88
	19628	Programmer Options, 142, 221, 222, 428, 435, 437, 444
	19629	Regularly Scheduled, 208
	19630	Remove Tas kman from WAIT State , 311
	19631	Routine Co mpare - Cu rrent with Previous, 436, 437
	19632	Routine Ed it, 432
	19633	Routine To ols, 428, 444
	19634	Routines b y Patch Nu mber, 432
	19635	Run MUnit Tests from Test Grou ps, 392
	19636	Send Alpha /Beta Usag e to Progr ammers, 18 6, 188
	19637	Startup PR OD check, 283
	19638	Stop Task Manager, 3 11
	19639	Systems Ma nager Menu , 142, 436
	19640	Test an op tion not i n your men u, 222
	19641	Types, 207
	19642	Update wit h Current Routines, 436, 437
	19643	USER TERMI NATE ROUTI NE (Obsole te), 279
	19644	Variable C hanger, 43 2
	19645	Verifier T ools, 436
	19646	Verifier T ools Menu, 436
	19647	Version Nu mber Updat e, 432
	19648	XPD BUILD NAMESPACE, 144
	19649	XPD COPY B UILD, 145
	19650	XPD INSTAL L BUILD, 1 65
	19651	XPD MAIN, 142
	19652	XQ UNREF’D OPTIONS, 221
	19653	XQAB ACTUA L OPTION U SAGE, 187
	19654	XQAB AUTO SEND, 186, 188
	19655	XQAB ERR D ATE/SITE/N UM/ROU/ERR , 188
	19656	XQAB ERROR LOG SERVE R, 185
	19657	XQAB ERROR LOG XMIT, 185, 186
	19658	XQAB LIST LOW USAGE OPTS, 188
	19659	XQAB MENU, 187
	19660	XQUIT (Men u Manager) , 208
	19661	XTFCE, 431
	19662	XTFCR, 431
	19663	XTMUNIT GR OUP EDIT, 392
	19664	XTMUNIT GR OUP RUN, 3 92
	19665	XT-OPTION TEST, 222
	19666	XTRDEL, 43 4
	19667	XTRGRPE, 4 31
	19668	XT-ROUTINE COMPARE, 434
	19669	XTSUMBLD-C HECK
	19670	Programmer Options M enu, 437, 438
	19671	XTV MENU M enu, 436
	19672	XT-VARIABL E CHANGER, 432
	19673	XT-VERSION NUMBER, 4 32
	19674	XTVR COMPA RE, 436, 4 37
	19675	XTVR UPDAT E, 436, 43 7
	19676	XU BLOCK C OUNT, 221, 259
	19677	XU CHECKSU M LOAD, 43 4
	19678	XU CHECKSU M REPORT, 433, 438
	19679	XU SID ASK , 283
	19680	XU SID STA RTUP, 283
	19681	XU USER SI GN-ON, 277
	19682	XU USER ST ART-UP, 27 8
	19683	Package-sp ecific Sig non Action s, 278
	19684	XU USER TE RMINATE, 2 79
	19685	XUEDITOPT, 207
	19686	XUINDEX, 4 29, 444
	19687	XUKERNEL, 189, 283
	19688	XUPR RTN E DIT, 432
	19689	XUPR RTN P ATCH, 432
	19690	XUPRGL, 22 2
	19691	XUPROG, 14 2, 428, 43 7, 444
	19692	XUPRROU, 4 32
	19693	XUPR-ROUTI NE-TOOLS, 428, 444
	19694	XUPR-RTN-T APE-CMP, 4 33
	19695	XUROUTINE IN, 434
	19696	XUROUTINE OUT, 434
	19697	XUSITEMGR, 187
	19698	XUSITEPARM , 189
	19699	ZTMQUEUABL E OPTIONS, 186
	19700	OPTSTAT^XU TMOPT, 323
	19701	Orientatio n, lx
	19702	OUT^XPDMEN U, 211
	19703	OUT^XPDPRO T, 215
	19704	Output Rou tines Opti on, 434
	19705	Overview
	19706	Alerts
	19707	Developer Tools, 10
	19708	Device Han dler
	19709	Developer Tools, 55
	19710	File Acces s Security
	19711	Developer Tools, 106
	19712	M Unit
	19713	Developer Tools, 392
	19714	Operating System Int erface
	19715	Developer Tools, 259
	19716	Security K eys
	19717	Developer Tools, 269
	19718	Signon/Sec urity
	19719	Developer Tools, 276
	19720	Spooling
	19721	Developer Tools, 299
	19722	TaskMan
	19723	Developer Tools, 301
	19724	XGF Functi on Library
	19725	Developer Tools, 483
	19726	XLF Functi on Library
	19727	Developer Tools, 500
	19728	OWNSKEY^XU SRB, 271
	19729	P
	19730	PACKAGE fi le (#9.4), 355
	19731	PACKAGE Fi le (#9.4), 143, 174, 181, 182, 183, 191, 201, 279, 357, 358, 400, 429, 439
	19732	Package Fi le Link (K IDS), 182
	19733	PACKAGE FI LE LINK Fi eld, 182, 183
	19734	Package Id entifier
	19735	Alert Iden tifier, 11
	19736	Convention s, 11
	19737	PACKAGE NA MESPACE OR PREFIX Fi eld (#23), 185
	19738	Package Re vision Dat a Node, 17 2
	19739	PackMan Co mpare Util ities, 434
	19740	Page Lengt h, 64
	19741	Parameter
	19742	Parameter Tools
	19743	Toolkit AP Is, 401
	19744	PARAMETER DEFINITION File (#89 89.51), 40 1, 403, 40 5, 410, 41 2
	19745	PARAMETER ENTITY Fil e (#8989.5 18), 400
	19746	Parameter Template
	19747	Parameter Tools
	19748	Toolkit AP Is, 401
	19749	PARAMETER TEMPLATE f ile (#8989 .52), 401
	19750	PARAMETER TEMPLATE F ile (#8989 .52), 412, 413
	19751	Parameter Tools
	19752	Toolkit AP Is, 400
	19753	Entity Def inition, 4 00
	19754	Instance D efinition, 401
	19755	Parameter Definition , 401
	19756	Parameter Template D efinition, 401
	19757	Value Defi nition, 40 1
	19758	Parameters
	19759	KIDS, 172
	19760	XPD NO_EPP _DELETE, 1 72
	19761	PARAMETERS File (#89 89.5), 401 , 403
	19762	Parameters , Site, 28 1
	19763	Parent Nod e, 586
	19764	PARENT^XUA F4, 130
	19765	Part 3 of Kernel Ins tall, 106
	19766	Partial DD (Some Fie lds) (KIDS ), 150
	19767	File Numbe r Level, 1 50
	19768	Multiple L evel, 150
	19769	PAT^XULMU, 205
	19770	PATCH APPL ICATION HI STORY Fiel d (#1105, Multiple), 191
	19771	Patches
	19772	History, x xi
	19773	PATIENT Fi le (#2), 1 1, 20, 26, 205, 206
	19774	PATIENT^XQ ALERT, 26
	19775	PCLEAR^%ZT LOAD, 337
	19776	PERSON CLA SS File (# 8932.1), 4 64, 465
	19777	Phantom Ju mp, 209
	19778	PKILL^%ZIS P, 71
	19779	Place Task man in a W AIT State Option, 31 1
	19780	POSTAL^XIP UTIL, 5
	19781	POSTALB^XI PUTIL, 8
	19782	Post-Execu tion Comma nds
	19783	ZTREQ (Tas kMan), 306
	19784	Post-execu tion comma nds - ZTRE Q, 306
	19785	POTENTIAL DUPLICATE THRESHOLD% , 362
	19786	PRD^DILFD, 172
	19787	Pre- and P ost-Instal l Routines
	19788	Special Fe atures (KI DS), 171
	19789	PREP^XGF, 490
	19790	PRE-TRANSP ORTATION R OUTINE Fie ld (#900), 170
	19791	Print Alph a/Beta Err ors (Date/ Site/Num/R ou/Err) Op tion, 188
	19792	Printing R outines
	19793	Routine To ols, 432
	19794	Problems R elated To Data Entry While Mer ging, 369
	19795	Programmer Options M enu, 142, 221, 222, 428, 435, 437, 444
	19796	Progress B ar Emulato r
	19797	Miscellane ous Develo per Tools, 225
	19798	PROTOCOL F ile (#101) , 101, 137 , 213, 214 , 215, 216 , 217, 461 , 462, 595
	19799	Protocols
	19800	KIDS, 157
	19801	Proxy
	19802	Applicatio n Proxy Us er, 285, 2 86
	19803	PS Anonymo us Directo ries, lxv
	19804	PSET^%ZISP , 72
	19805	PTPURG^XQA LBUTL, 20
	19806	Public Ide ntifier, 5 74
	19807	Purging
	19808	Alpha/Beta Tracking Data (KIDS ), 188
	19809	Purging th e Task Rec ord (TaskM an), 305
	19810	PUT^XPAR, 409
	19811	Q
	19812	Question M ark Help, lxiv
	19813	Question S ubscripts (KIDS), 17 5
	19814	Queueing t he Install Prompt (K IDS), 168
	19815	Queuers
	19816	Non-intera ctive, 329
	19817	Queuers (T askMan), 3 01
	19818	^%ZTLOAD, 301
	19819	EN^XUTMDEV Q, 302
	19820	Scheduled Options, 3 02
	19821	Queuing, 5 9, 61, 63
	19822	Spooler), 299
	19823	R
	19824	READ^XGF, 491
	19825	RECEIVE^XT KERMIT, 37 8
	19826	RECIPURG^X QALBUTL, 2 0
	19827	Reference Materials, lxiv
	19828	Reference Type
	19829	Controlled Subscript ion
	19830	$$CHECKAV^ XUSRB, 291
	19831	$$CHKDGT^X USNPI, 254
	19832	$$CREATE^X USAP, 285
	19833	$$KCHK^XUS RB, 480
	19834	$$NPI^XUSN PI, 255
	19835	$$QI^XUSNP I, 256
	19836	$$TAXIND^X USTAX, 257
	19837	$$TAXORG^X USTAX, 258
	19838	^XUSESIG, 90
	19839	AVHLPTXT^X US2, 284
	19840	CVC^XUSRB, 292
	19841	DELCOMP^XL FNAME2, 25 0
	19842	DIV4^XUSER , 472
	19843	DIVGET^XUS RB2, 481
	19844	DIVSET^XUS RB2, 481
	19845	DOLRO^%ZOS V, 263
	19846	DSD^ZISPL, 300
	19847	DSDOC^ZISP L, 300
	19848	EN^XPDIJ, 191
	19849	EN^XUTMTP, 324
	19850	EN1^XUPSQR Y, 46
	19851	GETPEER^%Z OSV, 298
	19852	INTRO^XUSR B, 293
	19853	LOGOUT^XUS RB, 293
	19854	MAIN^XUMFI , 135
	19855	MAIN^XUMFP , 136
	19856	SAVEMERG^X DRMERGB, 3 71
	19857	SETUP^XUSR B, 293
	19858	UPDCOMP^XL FNAME2, 25 1
	19859	USERINFO^X USRB2, 482
	19860	VALIDAV^XU SRB, 294
	19861	WITNESS^XU VERIFY, 29 7
	19862	Supported
	19863	$$%H^XLFDT , 503
	19864	$$ABS^XLFM TH, 529
	19865	$$ACCESS^X QCHK, 218
	19866	$$ACOS^XLF MTH, 530
	19867	$$ACOSDEG^ XLFMTH, 53 0
	19868	$$ACOSH^XL FHYPER, 52 3
	19869	$$ACOT^XLF MTH, 531
	19870	$$ACOTDEG^ XLFMTH, 53 1
	19871	$$ACOTH^XL FHYPER, 52 4
	19872	$$ACSC^XLF MTH, 532
	19873	$$ACSCDEG^ XLFMTH, 53 2
	19874	$$ACSCH^XL FHYPER, 52 4
	19875	$$ACTIVE^X UAF4, 121
	19876	$$ACTIVE^X USER, 467
	19877	$$ACTJ^%ZO SV, 262
	19878	$$ADD^XPDM ENU, 210
	19879	$$ADD^XPDP ROT, 213
	19880	$$ADD^XUSE RNEW, 290
	19881	$$ADDRESS^ XLFNSLK, 8 8
	19882	$$AESDECR^ XUSHSH, 48
	19883	$$AESENCR^ XUSHSH, 49
	19884	$$ASEC^XLF MTH, 533
	19885	$$ASECDEG^ XLFMTH, 53 3
	19886	$$ASECH^XL FHYPER, 52 5
	19887	$$ASIN^XLF MTH, 534
	19888	$$ASINDEG^ XLFMTH, 53 4
	19889	$$ASINH^XL FHYPER, 52 5
	19890	$$ASKSTOP^ %ZTLOAD, 3 33
	19891	$$ATAN^XLF MTH, 535
	19892	$$ATANDEG^ XLFMTH, 53 5
	19893	$$ATANH^XL FHYPER, 52 6
	19894	$$ATTRIB^M XMLDOM, 57 6
	19895	$$AVJ^%ZOS V, 263
	19896	$$B64DECD^ XUSHSH, 50
	19897	$$B64ENCD^ XUSHSH, 50
	19898	$$BASE^XLF UTL, 563
	19899	$$BLDNAME^ XLFNAME, 2 32
	19900	$$BSA^XLFM SMT, 549
	19901	$$CCD^XLFU TL, 564
	19902	$$CHECKAV^ XUVERIFY, 297
	19903	$$CHILD^MX MLDOM, 577
	19904	$$CHKSUM^X USESIG1, 9 1
	19905	$$CIRN^XUA F4, 122
	19906	$$CJ^XLFST R, 554
	19907	$$CLEANC^X LFNAME, 23 4
	19908	$$CMNT^MXM LDOM, 577
	19909	$$CMP^XUSE SIG1, 91
	19910	$$CNV^XLFU TL, 564
	19911	$$CODE2TXT ^XUA4A72, 464
	19912	$$COMCP^XP DUTL, 192
	19913	$$CONVERT^ XLFIPV, 56 7
	19914	$$COS^XLFM TH, 536
	19915	$$COSDEG^X LFMTH, 536
	19916	$$COSH^XLF HYPER, 526
	19917	$$COT^XLFM TH, 537
	19918	$$COTDEG^X LFMTH, 537
	19919	$$COTH^XLF HYPER, 527
	19920	$$CRC16^XL FCRC, 500
	19921	$$CRC32^XL FCRC, 502
	19922	$$CSC^XLFM TH, 538
	19923	$$CSCDEG^X LFMTH, 538
	19924	$$CSCH^XLF HYPER, 527
	19925	$$CURCP^XP DUTL, 193
	19926	$$CURRSURO ^XQALSURO, 39
	19927	$$DE^XUSES IG1, 92
	19928	$$DEA^XUSE R, 468
	19929	$$DEC^XLFU TL, 565
	19930	$$DECDMS^X LFMTH, 539
	19931	$$DECODE^X THCUTL, 37 7
	19932	$$DECRYP^X USRB1, 294
	19933	$$DEFDIR^% ZISH, 112
	19934	$$DEL^%ZIS H, 113
	19935	$$DELETE^X PDMENU, 21 0
	19936	$$DELETE^X PDPROT, 21 4
	19937	$$DEV^XUTM DEVQ, 312
	19938	$$DMSDEC^X LFMTH, 539
	19939	$$DOW^XLFD T, 503
	19940	$$DT^XLFDT , 504
	19941	$$DTIME^XU P, 465
	19942	$$DTR^XLFM TH, 540
	19943	$$E^XLFMTH , 540
	19944	$$EC^%ZOSV , 96
	19945	$$EN^MXMLD OM, 579
	19946	$$EN^XUSES IG1, 92
	19947	$$EN^XUWOR KDY, 229
	19948	$$ENCODE^X THCURL, 37 4
	19949	$$ENCRYP^X USRB1, 295
	19950	$$ESBLOCK^ XUSESIG1, 92
	19951	$$EXP^XLFM TH, 541
	19952	$$FIPS^XIP UTIL, 4
	19953	$$FIPSCHK^ XIPUTIL, 5
	19954	$$FMADD^XL FDT, 505
	19955	$$FMDIFF^X LFDT, 505
	19956	$$FMNAME^X LFNAME, 23 6
	19957	$$FMTE^XLF DT, 506
	19958	$$FMTH^XLF DT, 511
	19959	$$FMTHL7^X LFDT, 511
	19960	$$FORCEIP4 ^XLFIPV, 5 68
	19961	$$FORCEIP6 ^XLFIPV, 5 69
	19962	$$FTG^%ZIS H, 114
	19963	$$GATF^%ZI SH, 115
	19964	$$GET^XPAR , 405
	19965	$$GET^XUA4 A72, 464
	19966	$$GET^XUPA RAM, 280
	19967	$$GETMASTR ^XTID, 416
	19968	$$GETRPLC^ XTIDTRM(), 348
	19969	$$GETSTAT^ XTID, 417
	19970	$$GETSURO^ XQALSURO, 39
	19971	$$GETURL^X THC10, 372
	19972	$$GETVUID^ XTID, 419
	19973	$$GTF^%ZIS H, 116
	19974	$$HADD^XLF DT, 512
	19975	$$HANDLE^X USRB4, 295
	19976	$$HDIFF^XL FDT, 512
	19977	$$HL7TFM^X LFDT, 513
	19978	$$HLNAME^X LFNAME, 23 8
	19979	$$HTE^XLFD T, 515
	19980	$$HTFM^XLF DT, 517
	19981	$$ID^XUAF4 , 124
	19982	$$IDX^XUAF 4, 124
	19983	$$IEN^XUAF 4, 125
	19984	$$IEN^XUMF , 134
	19985	$$IEN^XUPS , 45
	19986	$$IEN2CODE ^XUA4A72, 465
	19987	$$INHIBIT^ XUSRB, 292
	19988	$$INSTALDT ^XPDUTL, 1 93
	19989	$$INVERT^X LFSTR, 555
	19990	$$JOB^%ZTL OAD, 336
	19991	$$KSP^XUPA RAM, 281
	19992	$$LAST^XPD UTL, 194
	19993	$$LEGACY^X UAF4, 125
	19994	$$LENGTH^X LFMSMT, 55 0
	19995	$$LGR^%ZOS V, 264
	19996	$$LIST^%ZI SH, 116
	19997	$$LJ^XLFST R, 555
	19998	$$LKOPT^XP DMENU, 211
	19999	$$LKPROT^X PDPROT, 21 5
	20000	$$LKUP^XPD KEY, 270
	20001	$$LKUP^XUA F4, 126
	20002	$$LKUP^XUP ARAM, 282
	20003	$$LN^XLFMT H, 541
	20004	$$LOG^XLFM TH, 542
	20005	$$LOOKUP^X USER, 473
	20006	$$LOW^XLFS TR, 556
	20007	$$MADD^XUA F4, 127
	20008	$$MAKEURL^ XTHCURL, 3 75
	20009	$$MAX^XLFM TH, 542
	20010	$$MIN^XLFM TH, 543
	20011	$$MV^%ZISH , 117
	20012	$$NAME^MXM LDOM, 580
	20013	$$NAME^XUA F4, 127
	20014	$$NAME^XUS ER, 475
	20015	$$NAMEFMT^ XLFNAME, 2 41
	20016	$$NEWCP^XP DUTL, 196
	20017	$$NEWERR^% ZTER, 99
	20018	$$NNT^XUAF 4, 128
	20019	$$NODEV^XU TMDEVQ, 31 6
	20020	$$NOW^XLFD T, 517
	20021	$$NS^XUAF4 , 128
	20022	$$O99^XUAF 4, 129
	20023	$$OPTDE^XP DUTL, 197
	20024	$$OS^%ZOSV , 265
	20025	$$PADD^XUA F4, 129
	20026	$$PARCP^XP DUTL, 197
	20027	$$PARENT^M XMLDOM, 58 0
	20028	$$PARSEURL ^XTHCURL, 376
	20029	$$PATCH^XP DUTL, 198
	20030	$$PENDING^ XQALBUTL, 18
	20031	$$PI^XLFMT H, 543
	20032	$$PKG^XPDU TL, 198
	20033	$$PKGPAT^X PDIP, 191
	20034	$$PKGPEND^ XQALBUTL, 19
	20035	$$PRNT^XUA F4, 130
	20036	$$PROD^XUP ROD, 283
	20037	$$PRODE^XP DUTL, 199
	20038	$$PROVIDER ^XUSER, 47 6
	20039	$$PSET^%ZT LOAD, 337
	20040	$$PWD^%ZIS H, 119
	20041	$$PWR^XLFM TH, 544
	20042	$$QQ^XUTMD EVQ, 318
	20043	$$RENAME^X PDKEY, 270
	20044	$$REPEAT^X LFSTR, 557
	20045	$$REPLACE^ XLFSTR, 55 7
	20046	$$REQQ^XUT MDEVQ, 321
	20047	$$RES^XUDH SET, 58
	20048	$$REWIND^% ZIS, 70
	20049	$$RF^XUAF4 , 131
	20050	$$RJ^XLFST R, 558
	20051	$$RPLCLST^ XTIDTRM, 3 49
	20052	$$RPLCMNT^ XTIDTRM, 3 50
	20053	$$RPLCTRL^ XTIDTRM, 3 51
	20054	$$RPLCVALS ^XTIDTRM, 352
	20055	$$RSADECR^ XUSHSH, 51
	20056	$$RSAENCR^ XUSHSH, 52
	20057	$$RT^XUAF4 , 131
	20058	$$RTD^XLFM TH, 544
	20059	$$RTNUP^XP DUTL, 199
	20060	$$S^%ZTLOA D, 343
	20061	$$SCH^XLFD T, 518
	20062	$$SCREEN^X TID, 420
	20063	$$SD^XLFMT H, 545
	20064	$$SDEA^XUS ER, 477
	20065	$$SDETOX^X USER, 471
	20066	$$SEC^XLFD T, 521
	20067	$$SEC^XLFM TH, 545
	20068	$$SECDEG^X LFMTH, 546
	20069	$$SECH^XLF HYPER, 528
	20070	$$SENTENCE ^XLFSTR, 5 59
	20071	$$SETMASTR ^XTID, 422
	20072	$$SETRPLC^ XTIDTRM, 3 53
	20073	$$SETSTAT^ XTID, 423
	20074	$$SETUP1^X QALERT, 31
	20075	$$SETVUID^ XTID, 425
	20076	$$SHAHASH^ XUSHSH, 53
	20077	$$SIBLING^ MXMLDOM, 5 81
	20078	$$SIN^XLFM TH, 546
	20079	$$SINDEG^X LFMTH, 547
	20080	$$SINH^XLF HYPER, 528
	20081	$$SQRT^XLF MTH, 547
	20082	$$STA^XUAF 4, 133
	20083	$$STATUS^% ZISH, 119
	20084	$$STRIP^XL FSTR, 559
	20085	$$SYMENC^M XMLUTL, 58 8
	20086	$$TAN^XLFM TH, 548
	20087	$$TANDEG^X LFMTH, 548
	20088	$$TANH^XLF HYPER, 529
	20089	$$TEMP^XLF MSMT, 551
	20090	$$TEXT^MXM LDOM, 581
	20091	$$TF^XUAF4 , 133
	20092	$$TITLE^XL FSTR, 560
	20093	$$TM^%ZTLO AD, 345
	20094	$$TRIM^XLF STR, 561
	20095	$$TYPE^XPD MENU, 212
	20096	$$TYPE^XPD PROT, 217
	20097	$$TZ^XLFDT , 522
	20098	$$UP^XLFST R, 562
	20099	$$UPCP^XPD UTL, 200
	20100	$$VALIDATE ^XLFIPV, 5 70
	20101	$$VALUE^MX MLDOM, 582
	20102	$$VCD^XLFU TL, 566
	20103	$$VDEA^XUS ER, 479
	20104	$$VER^XPDU TL, 200
	20105	$$VERCP^XP DUTL, 201
	20106	$$VERSION^ %ZOSV, 268
	20107	$$VERSION^ XLFIPV, 57 1
	20108	$$VERSION^ XPDUTL, 20 1
	20109	$$VOLUME^X LFMSMT, 55 2
	20110	$$VPID^XUP S, 45
	20111	$$WEIGHT^X LFMSMT, 55 3
	20112	$$WHAT^XUA F4, 134
	20113	$$WITHIN^X LFDT, 522
	20114	$$WORKDAY^ XUWORKDY, 230
	20115	$$WORKPLUS ^XUWORKDY, 231
	20116	$$XMLHDR^M XMLUTL, 58 8
	20117	^%ZIS, 58
	20118	^%ZISC, 71
	20119	^%ZTER, 97
	20120	^%ZTLOAD, 325
	20121	^XQDATE, 2 27
	20122	^XUP, 276
	20123	^XUS, 276
	20124	^XUSCLEAN, 277
	20125	^XUVERIFY, 296
	20126	^XUWORKDY, 227
	20127	^ZU, 277
	20128	ACTION^XQA LERT, 22
	20129	ACTION^XQH 4, 110
	20130	ADD^XPAR, 401
	20131	ADDPAT^XUL MU, 205
	20132	AHISTORY^X QALBUTL, 1 3
	20133	ALERTDAT^X QALBUTL, 1 5
	20134	BLDLST^XPA REDIT, 410
	20135	BMES^XPDUT L, 192
	20136	CALL^%ZIST CP, 79
	20137	CCODE^XIPU TIL, 3
	20138	CDSYS^XUAF 4, 121
	20139	CHG^XPAR, 402
	20140	CHGA^XGF, 485
	20141	CHILDREN^X UAF4, 122
	20142	CLEAN^XGF, 486
	20143	CLEANUP^XU LMU, 202
	20144	CLEAR^XGF, 487
	20145	CLOSE^%ZIS H, 112
	20146	CLOSE^%ZIS TCP, 80
	20147	CLOSE^%ZIS UTL, 81
	20148	CMNT^MXMLD OM, 578
	20149	DE^XUSHSHP , 93
	20150	DEL^XPAR, 402
	20151	DEL^XPDKEY , 269
	20152	DELETE^MXM LDOM, 578
	20153	DELETE^XQA LERT, 23
	20154	DELETEA^XQ ALERT, 24
	20155	DELSTAT^XQ ALBUTL, 16
	20156	DESC^%ZTLO AD, 333
	20157	DEVICE^XUD HGUI, 55
	20158	DISP^XQORM 1, 463
	20159	DISP^XUTMO PT, 322
	20160	DK^XTLKMGR , 383
	20161	DLL^XTLKMG R, 383
	20162	DQ^%ZTLOAD , 334
	20163	DSH^XTLKMG R, 384
	20164	DSY^XTLKMG R, 384
	20165	EDIT^XPARE DIT, 410
	20166	EDIT^XUTMO PT, 323
	20167	EDITPAR^XP AREDIT, 41 0
	20168	EN^MXMLPRS E, 583
	20169	EN^XDRMERG , 368
	20170	EN^XPAR, 4 03
	20171	EN^XPAREDI T, 411
	20172	EN^XQH, 10 9
	20173	EN^XQOR, 4 61
	20174	EN^XQORM, 462
	20175	EN^XUA4A71 , 226
	20176	EN^XUSHSHP , 94
	20177	EN^XUTMDEV Q, 314
	20178	EN1^XQH, 1 09
	20179	EN1^XQOR, 461
	20180	ENDR^%ZISS , 73
	20181	ENS^%ZISS, 74
	20182	ENVAL^XPAR , 404
	20183	EXIT^XPDID , 226
	20184	F4^XUAF4, 123
	20185	FIND^XPDPR OT, 214
	20186	FORWARD^XQ ALFWD, 37
	20187	FRAME^XGF, 488
	20188	GETACT^XQA LERT, 25
	20189	GETENT^XPA REDIT, 411
	20190	GETENV^%ZO SV, 264
	20191	GETIREF^XT ID, 414
	20192	GETLST^XPA R, 406
	20193	GETPAR^XPA REDIT, 412
	20194	GETWP^XPAR , 407
	20195	GKILL^%ZIS S, 78
	20196	GSET^%ZISS , 78
	20197	H^XUS, 277 , 283
	20198	HASH^XUSHS HP, 94
	20199	HLP1^%ZIS, 68
	20200	HLP2^%ZIS, 69
	20201	HOME^%ZIS, 69
	20202	INIT^XPDID , 225
	20203	INITKB^XGF , 489
	20204	IOXY^XGF, 489
	20205	ISQED^%ZTL OAD, 334
	20206	K^XTLKMGR, 385
	20207	KILL^%ZISS , 79
	20208	KILL^%ZTLO AD, 336
	20209	KILL^XUSCL EAN, 289
	20210	L^XTLKMGR, 385
	20211	LKUP^XTLKM GR, 386
	20212	LOGRSRC^%Z OSV, 264
	20213	LOOKUP^XUA F4, 126
	20214	MAIL^XLFNS LK, 89
	20215	MES^XPDUTL , 195
	20216	MSG^XQOR, 462
	20217	NAMECOMP^X LFNAME, 24 0
	20218	NDEL^XPAR, 408
	20219	NOTIPURG^X QALBUTL, 1 7
	20220	OP^XQ92, 2 18
	20221	OP^XQCHK, 219
	20222	OPEN^%ZISH , 118
	20223	OPEN^%ZISU TL, 81
	20224	OPKG^XUHUI , 101
	20225	OPTION^%ZT LOAD, 337
	20226	OPTSTAT^XU TMOPT, 323
	20227	OUT^XPDMEN U, 211
	20228	OUT^XPDPRO T, 215
	20229	OWNSKEY^XU SRB, 271
	20230	PARENT^XUA F4, 130
	20231	PAT^XULMU, 205
	20232	PATIENT^XQ ALERT, 26
	20233	PCLEAR^%ZT LOAD, 337
	20234	PKILL^%ZIS P, 71
	20235	POSTAL^XIP UTIL, 5
	20236	POSTALB^XI PUTIL, 8
	20237	PREP^XGF, 490
	20238	PSET^%ZISP , 72
	20239	PTPURG^XQA LBUTL, 20
	20240	PUT^XPAR, 409
	20241	READ^XGF, 491
	20242	RECEIVE^XT KERMIT, 37 8
	20243	RECIPURG^X QALBUTL, 2 0
	20244	REMVSURO^X QALSURO, 4 0
	20245	RENAME^XPD MENU, 212
	20246	RENAME^XPD PROT, 216
	20247	REP^XPAR, 409
	20248	REQ^%ZTLOA D, 338
	20249	RESCH^XUTM OPT, 324
	20250	RESETKB^XG F, 493
	20251	RESTART^XD RMERG, 370
	20252	RESTORE^XG F, 493
	20253	RFILE^XTKE RM4, 378
	20254	RMDEV^%ZIS UTL, 83
	20255	RTN^%ZTLOA D, 342
	20256	SAVDEV^%ZI SUTL, 84
	20257	SAVE^XGF, 494
	20258	SAY^XGF, 4 95
	20259	SAYU, 496
	20260	SEND^XTKER MIT, 379
	20261	SET^XUPARA M, 282
	20262	SET^XUS1A, 284
	20263	SETA^XGF, 497
	20264	SETCLEAN^X ULMU, 203
	20265	SETENV^%ZO SV, 265
	20266	SETNM^%ZOS V, 266
	20267	SETSURO1^X QALSURO, 4 1
	20268	SETUP^XQAL ERT, 27
	20269	SH^XTLKMGR , 390
	20270	SIBLING^XU AF4, 132
	20271	SIG^XUSESI G, 90
	20272	STAT^%ZTLO AD, 343
	20273	STDNAME^XL FNAME, 245
	20274	SUROFOR^XQ ALSURO, 42
	20275	SUROLIST^X QALSURO, 4 3
	20276	SY^XTLKMGR , 391
	20277	T0^%ZOSV, 266
	20278	T1^%ZOSV, 267
	20279	TED^XPARED IT, 412
	20280	TEDH^XPARE DIT, 413
	20281	TEXT^MXMLD OM, 582
	20282	TITLE^XPDI D, 225
	20283	TOUCH^XUSC LEAN, 312
	20284	UNCLEAN^XU LMU, 204
	20285	UNWIND^%ZT ER, 100
	20286	UPDATE^XPD ID, 190
	20287	USE^%ZISUT L, 84
	20288	USER^XQALE RT, 36
	20289	USERDATA^X QALBUTL, 2 1
	20290	USERLIST^X QALBUTL, 2 2
	20291	WIN^XGF, 4 98
	20292	XREF^XQORM , 463
	20293	XTLKKWL^XT LKKWL, 382
	20294	ZTSAVE^%ZT LOAD, 345
	20295	Regularly Scheduled Options, 2 08
	20296	Re-Indexin g Files (K IDS), 155
	20297	REMOTE PRO CEDURE Fil e (#8994), 285
	20298	Remove Tas kman from WAIT State Option, 3 11
	20299	REMVSURO^X QALSURO, 4 0
	20300	RENAME^XPD MENU, 212
	20301	RENAME^XPD PROT, 216
	20302	REP^XPAR, 409
	20303	REQ^%ZTLOA D, 338
	20304	Required B uilds (KID S), 181
	20305	RESCH^XUTM OPT, 324
	20306	RESETKB^XG F, 493
	20307	Resource D evices
	20308	SYNC FLAGs , 87
	20309	RESTART^XD RMERG, 370
	20310	RESTART^ZT MB Direct Mode Utili ty, 311
	20311	RESTORE^XG F, 493
	20312	Revision H istory, ii
	20313	Patches, x xi
	20314	Rewinding Devices, 7 0
	20315	RFILE^XTKE RM4, 378
	20316	Right Marg in, 64, 66
	20317	RMDEV^%ZIS UTL, 83
	20318	ROOM-BED F ile (#405. 4), 400
	20319	Routine Co mpare - Cu rrent with Previous Option, 43 6, 437
	20320	Routine Ed it Option, 432
	20321	Routine Ed itor, 222, 224
	20322	ROUTINE Fi le (#9.8), 158, 223, 433, 434
	20323	Routine In stall Opti ons (KIDS) , 167
	20324	Routine To ols, 427
	20325	^ %RR Dire ct Mode Ut ility, 427
	20326	^ %RS Dire ct Mode Ut ility, 428
	20327	^%INDEX Di rect Mode Utility, 4 27
	20328	^%Z Direct Mode Util ity, 427
	20329	^%ZTP1 Dir ect Mode U tility, 42 7
	20330	^%ZTPP Dir ect Mode U tility, 42 7
	20331	^%ZTRDEL D irect Mode Utility, 427
	20332	^XINDEX Di rect Mode Utility, 4 27
	20333	^XTFCE Dir ect Mode U tility, 42 7
	20334	^XTFCR Dir ect Mode U tility, 42 7
	20335	^XTRCMP Di rect Mode Utility, 4 27
	20336	^XTRGRPE D irect Mode Utility, 427
	20337	^XTVCHG Di rect Mode Utility, 4 27
	20338	^XTVNUM Di rect Mode Utility, 4 27
	20339	Analyzing Routines, 429
	20340	Compare lo cal/nation al checksu ms report Option, 43 3
	20341	Compare Ro utines on Tape to Di sk Option, 433
	20342	Compare Tw o Routines Option, 4 34
	20343	Comparing Routines, 433
	20344	Delete Rou tines Opti on, 434
	20345	Deleting
	20346	Routines, 434
	20347	Direct Mod e Utilitie s, 427
	20348	Flow Chart Entire Ro utine Opti on, 431
	20349	Flow Chart from Entr y Point Op tion, 431
	20350	Group Rout ine Edit O ption, 431
	20351	Input Rout ines Optio n, 434
	20352	List Routi nes option , 432
	20353	Load Routi nes, 434
	20354	Load/refre sh checksu m values i nto ROUTIN E file Opt ion, 434
	20355	Output Rou tines Opti on, 434
	20356	Printing R outines, 4 32
	20357	Routine Ed it Option, 432
	20358	Routine To ols
	20359	Editing Ro utines, 43 1
	20360	Routines b y Patch Nu mber Optio n, 432
	20361	Save Routi nes, 434
	20362	TE^XTRCMP Direct Mod e Utility, 427
	20363	Variable C hanger Opt ion, 432
	20364	Version Nu mber Updat e Option, 432
	20365	Routine To ols Menu, 428, 444
	20366	Routines
	20367	%RR, 434
	20368	%RS, 434
	20369	%ZTRDEL, 4 34
	20370	^XTMUNIT, 392, 393
	20371	^XTMUNIT1, 392
	20372	^XTMZZUT1, 393
	20373	^XUP, 209
	20374	CHCEK1^XTS UMBLD, 438
	20375	CHECK^XTSU MBLD, 433, 435, 438
	20376	CHECK1^XTS UMBLD, 433 , 435, 438
	20377	KIDS, 158
	20378	Load, 434
	20379	MXMLDOM, 5 74, 576
	20380	Save, 434
	20381	XQ1, 209
	20382	XQ12, 278
	20383	XTMUNIT, 3 94, 395
	20384	XTRCMP, 43 3, 434
	20385	XTVCHG, 43 2
	20386	XTVNUM, 43 2
	20387	ZTMGRSET, 222
	20388	Routines b y Patch Nu mber Optio n, 432
	20389	RPCs
	20390	XUPS PERSO NQUERY, 46
	20391	XUS KEY CH ECK, 271
	20392	RT logging , 266
	20393	RTN^%ZTLOA D, 342
	20394	RUM, 264, 265
	20395	Run MUnit Tests from Test Grou ps Option, 392
	20396	RUN^ZTMKU Direct Mod e Utility, 311
	20397	RUNSET^XTM UNIT(setna me) Direct Mode Util ity, 392
	20398	S
	20399	S^%ZTLOAD, 304
	20400	SAC
	20401	VA Program ming Stand ards and C onventions , 439
	20402	SAVDEV^%ZI SUTL, 84
	20403	Save Routi nes, 434
	20404	SAVE^XGF, 494
	20405	SAVEMERG^X DRMERGB, 3 71
	20406	SAX Interf ace, 573, 587
	20407	SAY^XGF, 4 95
	20408	SAYU^XGF, 496
	20409	SECURITY K EY File (# 19.1), 269
	20410	Security K eys
	20411	$$KCHK^XUS RB, 480
	20412	$$LKUP^XPD KEY, 270
	20413	$$RENAME^X PDKEY, 270
	20414	APIs, 269
	20415	DEL^XPDKEY , 269
	20416	Developer Tools
	20417	Overview, 269
	20418	Key Lookup , 269
	20419	OWNSKEY^XU SRB, 271
	20420	Person Loo kup, 269
	20421	XUMGR, 222
	20422	XUPROG, 14 2, 222, 42 8, 434, 44 4
	20423	XUPROGMODE , 222, 428 , 431, 432 , 434, 438
	20424	Selecting Fields to Compare in Candidate Collectio n, Duplica te Resolut ion Utilit ies, 360
	20425	Selecting Templates (KIDS), 16 0
	20426	Self-Conta ined Routi ne (KIDS), 165
	20427	Send Alpha /Beta Usag e to Progr ammers Opt ion, 186, 188
	20428	SEND^XTKER MIT, 379
	20429	Sending Se curity Cod es (KIDS), 149
	20430	Server Opt ions
	20431	Appending Text to a Server Req uest Bulle tin or Mai lman Reply , 274
	20432	Customizin g a Server Request B ulletin, 2 74
	20433	Developer Tools, 273
	20434	Key Variab les, 273
	20435	Tools for Processing Server Re quests, 27 3
	20436	SERVICE/SE CTION File (#49), 33 , 400
	20437	SET^XUPARA M, 282
	20438	SET^XUS1A, 284
	20439	SETA^XGF, 497
	20440	SETCLEAN^X ULMU, 203
	20441	SETENV^%ZO SV, 265
	20442	SETNM^%ZOS V, 266
	20443	SETSURO1^X QALSURO, 4 1
	20444	Setting a File’s Pac kage Revis ion Data N ode (Post- Install) ( KIDS), 172
	20445	SETUP^XQAL ERT, 27
	20446	SETUP^XUSR B, 293
	20447	SH^XTLKMGR , 390
	20448	Sibling No de, 587
	20449	SIBLING^XU AF4, 132
	20450	SIG^XUSESI G, 90
	20451	SIGN-ON LO G File (#3 .081), 277
	20452	Signon/Sec urity
	20453	$$PROD^XUP ROD, 283
	20454	$$ADD^XUSE RNEW, 290
	20455	$$CHECKAV^ XUSRB, 291
	20456	$$CHECKAV^ XUVERIFY, 297
	20457	$$CREATE^X USAP, 285
	20458	$$DECRYP^X USRB1, 294
	20459	$$ENCRYP^X USRB1, 295
	20460	$$GET^XUPA RAM, 280
	20461	$$HANDLE^X USRB4, 295
	20462	$$INHIBIT^ XUSRB, 292
	20463	$$KSP^XUPA RAM, 281
	20464	$$LKUP^XUP ARAM, 282
	20465	^XUP Direc t Mode Uti lity, 276
	20466	^XUS Direc t Mode Uti lity, 276
	20467	^XUSCLEAN Direct Mod e Utility, 277
	20468	^XUVERIFY, 296
	20469	^ZU Direct Mode Util ity, 277
	20470	APIs, 280
	20471	AVHLPTXT^X US2, 284
	20472	Creating a Package-s pecific Us er Termina tion Actio n, 279
	20473	CVC^XUSRB, 292
	20474	Developer Tools
	20475	Overview, 276
	20476	Direct Mod e Utilitie s, 276
	20477	^XUP, 276
	20478	^XUS, 276
	20479	^XUSCLEAN, 277
	20480	^ZU, 277
	20481	H^XUS, 277
	20482	GETPEER^%Z OSV, 298
	20483	H^XUS, 283
	20484	H^XUS Dire ct Mode Ut ility, 277
	20485	INTRO^XUSR B, 293
	20486	KILL^XUSCL EAN, 289
	20487	LOGOUT^XUS RB, 293
	20488	SET^XUPARA M, 282
	20489	SET^XUS1A, 284
	20490	SETUP^XUSR B, 293
	20491	VALIDAV^XU SRB, 294
	20492	WITNESS^XU VERIFY, 29 7
	20493	XU USER SI GN-ON Opti on, 277
	20494	XU USER ST ART-UP Opt ion, 278
	20495	Package-sp ecific Sig non Action s, 278
	20496	XU USER TE RMINATE Op tion, 279
	20497	Signon/sec urity Func tions
	20498	SIG^XUSESI G, 90
	20499	Simple API for XML ( SAX), 573, 587
	20500	Site Param eters, 281
	20501	Skip Insta lling or D elete a Ro utine (KID S), 167
	20502	Skipping I nstallatio n Question s (KIDS), 175
	20503	Slave Prin ters, 63
	20504	Software D isclaimer, lx
	20505	Software-w ide Variab les, Prote cting, 289
	20506	Soundex
	20507	$$EN^XUA4A 71, 226
	20508	SPOOL DATA File (#3. 519), 300
	20509	SPOOL DOCU MENT File (#3.51), 3 00
	20510	Spooling
	20511	APIs, 300
	20512	Developer Tools
	20513	Overview, 299
	20514	DSD^ZISPL, 300
	20515	DSDOC^ZISP L, 300
	20516	Site Param eters, 281
	20517	Spool Devi ce, 63
	20518	Startup PR OD check O ption, 283
	20519	STAT^%ZTLO AD, 343
	20520	STATE File (#5), 3, 6, 8
	20521	STATION NU MBER Field (#99), 13 3, 135
	20522	STDNAME^XL FNAME, 245
	20523	Stop Reque sts, Check ing for (T askMan), 3 04
	20524	Stop Task Manager Op tion, 311
	20525	STOP^ZTMKU Direct Mo de Utility , 311
	20526	Stopping t asks, 343
	20527	String Fun ctions
	20528	$$CJ^XLFST R, 554
	20529	$$INVERT^X LFSTR, 555
	20530	$$LJ^XLFST R, 555
	20531	$$LOW^XLFS TR, 556
	20532	$$REPEAT^X LFSTR, 557
	20533	$$REPLACE^ XLFSTR, 55 7
	20534	$$RJ^XLFST R, 558
	20535	$$SENTENCE ^XLFSTR, 5 59
	20536	$$STRIP^XL FSTR, 559
	20537	$$TITLE^XL FSTR, 560
	20538	$$TRIM^XLF STR, 561
	20539	$$UP^XLFST R, 562
	20540	String Fun ctions (XL F), 554
	20541	Subtype, 6 4
	20542	SUROFOR^XQ ALSURO, 42
	20543	SUROLIST^X QALSURO, 4 3
	20544	SURROGATE END DATE/T IME Field (#.04), 43
	20545	SURROGATE FOR ALERTS Field(#.0 2), 43
	20546	SURROGATE START DATE /TIME Fiel d (#.03), 43
	20547	SY^XTLKMGR , 391
	20548	Symbols
	20549	Found in t he Documen tation, lx i
	20550	SYNC FLAG, 310
	20551	SYNC FLAGs , 87
	20552	SYNC FLAGs to Contro l Sequence s of Tasks , 310
	20553	System Ide ntifier, 5 74
	20554	Systems Ma nager Menu , 142, 436
	20555	T
	20556	T0^%ZOSV, 266
	20557	T1^%ZOSV, 267
	20558	Table of C ontents, x xii
	20559	Tables, lv iii
	20560	TASK SYNC FLAG File (#14.8), 3 10, 311
	20561	TaskMan
	20562	$$ASKSTOP^ %ZTLOAD, 3 33
	20563	$$DEV^XUTM DEVQ, 312
	20564	$$JOB^%ZTL OAD, 336
	20565	$$NODEV^XU TMDEVQ, 31 6
	20566	$$PSET^%ZT LOAD, 337
	20567	$$QQ^XUTMD EVQ, 318
	20568	$$REQQ^XUT MDEVQ, 321
	20569	$$S^%ZTLOA D, 343
	20570	$$TM^%ZTLO AD, 345
	20571	^%ZTLOAD, 87, 325
	20572	APIs, 312
	20573	Checking E nvironment , 311
	20574	DESC^%ZTLO AD, 333
	20575	Developer Tools
	20576	Overview, 301
	20577	Direct Mod e Utilitie s, 311
	20578	^ZTMB, 311
	20579	^ZTMCHK, 3 11
	20580	^ZTMON, 31 1
	20581	Check Envi ronment, 3 11
	20582	Remove Tas kman from WAIT State Option, 3 11
	20583	Restart, 3 11
	20584	RESTART^ZT MB, 311
	20585	RUN^ZTMKU, 311
	20586	Starting, 311
	20587	STOP^ZTMKU , 311
	20588	Stopping, 311
	20589	WAIT^ZTMKU , 311
	20590	DISP^XUTMO PT, 322
	20591	DQ^%ZTLOAD , 334
	20592	EDIT^XUTMO PT, 323
	20593	EN^XUTMDEV Q, 314
	20594	EN^XUTMTP, 324
	20595	How to Wri te Code to Queue Tas ks, 301
	20596	ISQED^%ZTL OAD, 334
	20597	KILL^%ZTLO AD, 336
	20598	Monitoring , 311
	20599	OPTION^%ZT LOAD, 337
	20600	OPTSTAT^XU TMOPT, 323
	20601	PCLEAR^%ZT LOAD, 337
	20602	Placing in a WAIT St ate, 311
	20603	Queuers, 3 01
	20604	Removing f rom WAIT S tate, 311
	20605	REQ^%ZTLOA D, 338
	20606	RESCH^XUTM OPT, 324
	20607	Restarting , 311
	20608	RTN^%ZTLOA D, 342
	20609	Starting, 311
	20610	Stopping, 311
	20611	SYNC FLAGs , 87
	20612	Task Statu s, 343
	20613	Tasks, 303
	20614	TOUCH^XUSC LEAN, 312
	20615	ZTSAVE^%ZT LOAD, 345
	20616	TaskMan (D CL context ), 326
	20617	Tasks
	20618	^%ZIS Call within a Task, 307
	20619	^%ZTLOAD c all within a task, 3 07
	20620	Destinatio n, 304
	20621	Device, 30 4
	20622	DT Variabl e, 303
	20623	DUZ Array, 303
	20624	Error Trap , 304
	20625	IO* Array, 303
	20626	Post-execu tion comma nds, 306
	20627	Priority, 304
	20628	Purging th e Task Rec ord, 305
	20629	Queuing wi th no I/O device, 32 9
	20630	S^%ZTLOAD, 304
	20631	Saved Vari ables, 304
	20632	Stop Reque sts, 304
	20633	SYNC FLAGs , 310
	20634	TaskMan, 3 03
	20635	Tools, 304
	20636	Two-step t asks
	20637	Long Runni ng Tasks, 307, 308
	20638	ZTDESC Var iable, 303
	20639	ZTDTH Vari able, 303
	20640	ZTIO Varia ble, 303
	20641	ZTQUEUED v ariable, 3 06
	20642	ZTQUEUED V ariable, 3 03
	20643	ZTREQ, 306
	20644	ZTREQ Vari able, 305
	20645	ZTRTN Vari able, 303
	20646	ZTSK Varia ble, 304
	20647	ZTSTOP Var iable, 304 , 305
	20648	TASKS File (#14.4), 304, 305, 334
	20649	TE^XTRCMP Direct Mod e Utility, 427, 433
	20650	TEAM File (#404.51), 400
	20651	TED^XPARED IT, 412
	20652	TEDH^XPARE DIT, 413
	20653	Templates
	20654	Lock Templ ate, 206
	20655	Templates (KIDS), 16 0
	20656	Term Defin itions and XML Parse r Concept, 574
	20657	Terminal S erver, 60, 63
	20658	TERMINAL T YPE File ( #3.2), 60, 64, 72, 7 3, 74
	20659	Terminatin g
	20660	Alpha/Beta Tracking
	20661	Local Test Software Option Usa ge, 189
	20662	National R elease Sof tware Opti on Usage, 189
	20663	Alpha/Beta Tracking (KIDS), 18 8
	20664	Terminatio n Action, Creating, 279
	20665	Test an op tion not i n your men u Option, 222
	20666	TEXT^MXMLD OM, 582
	20667	TIME ZONE field (#1) , 522
	20668	TIMED READ (# OF SEC ONDS) Fiel d (#200.1) , 466
	20669	TIMED READ (# OF SEC ONDS) Fiel d (#51.1), 466
	20670	TITLE^XPDI D, 225
	20671	Toolkit
	20672	APIs, 346
	20673	Data Stand ardization APIs, 346
	20674	Developer Tools, 346
	20675	Direct Mod e Utilitie s
	20676	Miscellane ous Tools, 221
	20677	Routine To ols, 427
	20678	Verificati on Tools, 435
	20679	Duplicate Record Mer ge
	20680	RESTART^XD RMERG, 370
	20681	SAVEMERG^X DRMERGB, 3 71
	20682	Duplicate Record Mer ge APIs, 3 55
	20683	Get Field Values of Final Repl acement Te rm (Term/C oncept)
	20684	$$RPLCVALS ^XTIDTRM, 352
	20685	Get List o f Replacem ent Terms, w/Optiona l Status D ate and Hi story (Ter m/Concept)
	20686	$$RPLCLST^ XTIDTRM, 3 49
	20687	Get Mapped Terms (Te rm/Concept )
	20688	GETRPLC^XT IDTRM, 348
	20689	Get Replac ement Trai l for Term , with Rep laced ”BY” and Repla cement ”FO R” Terms ( Term/Conce pt)
	20690	$$RPLCTRL^ XTIDTRM, 3 51
	20691	HTTP Clien t APIs, 37 1
	20692	HTTP Clien t Helper
	20693	$$DECODE^X THCUTL, 37 7
	20694	$$ENCODE^X THCURL, 37 4
	20695	$$GETURL^X THC10, 372
	20696	$$MAKEURL^ XTHCURL, 3 75
	20697	$$PARSEURL ^XTHCURL, 376
	20698	Kermit
	20699	RECEIVE^XT KERMIT, 37 8
	20700	RFILE^XTKE RM4, 378
	20701	SEND^XTKER MIT, 379
	20702	KERMIT API s, 378
	20703	M One Term to Anothe r (Term/Co ncept)
	20704	$$RPLCMNT^ XTIDTRM, 3 50
	20705	Multi-Term Look-Up ( MTLU)
	20706	APIs, 381
	20707	DK^XTLKMGR , 383
	20708	DLL^XTLKMG R, 383
	20709	DSH^XTLKMG R, 384
	20710	DSY^XTLKMG R, 384
	20711	K^XTLKMGR, 385
	20712	L^XTLKMGR, 385
	20713	LKUP^XTLKM GR, 386
	20714	SH^XTLKMGR , 390
	20715	SY^XTLKMGR , 391
	20716	XTLKKWL^XT LKKWL, 382
	20717	Multi-Term Look-Up ( MTLU) APIs , 381
	20718	Parameter Tools
	20719	$$GET^XPAR , 405
	20720	ADD^XPAR, 401
	20721	BLDLST^XPA REDIT, 410
	20722	CHG^XPAR, 402
	20723	DEL^XPAR, 402
	20724	EDIT^XPARE DIT, 410
	20725	EDITPAR^XP AREDIT, 41 0
	20726	EN^XDRMERG , 368
	20727	EN^XPAR, 4 03
	20728	EN^XPAREDI T, 411
	20729	Entity Def inition, 4 00
	20730	ENVAL^XPAR , 404
	20731	GETENT^XPA REDIT, 411
	20732	GETLST^XPA R, 406
	20733	GETPAR^XPA REDIT, 412
	20734	GETWP^XPAR , 407
	20735	Instance D efinition, 401
	20736	NDEL^XPAR, 408
	20737	Parameter Definition , 401
	20738	Parameter Template D efinition, 401
	20739	PUT^XPAR, 409
	20740	REP^XPAR, 409
	20741	TED^XPARED IT, 412
	20742	TEDH^XPARE DIT, 413
	20743	Value Defi nition, 40 1
	20744	Parameter Tools APIs , 400
	20745	Replacemen t Relation ships, 347
	20746	Set Replac ement Term s (Term/Co ncept)
	20747	SETRPLC^XT IDTRM, 353
	20748	VHA Unique ID (VUID)
	20749	$$GETMASTR ^XTID, 416
	20750	$$GETSTAT^ XTID, 417
	20751	$$GETVUID^ XTID, 419
	20752	$$SCREEN^X TID, 420
	20753	$$SETMASTR ^XTID, 422
	20754	$$SETSTAT^ XTID, 423
	20755	$$SETVUID^ XTID, 425
	20756	GETIREF^XT ID, 414
	20757	VHA Unique ID (VUID) APIs, 414
	20758	XML Parser (VistA) A PIs, 573, 574
	20759	Toolkit Qu euable Opt ions menu
	20760	Errors Log ged in Alp ha/Beta Te st (QUEUED ) Option, 185, 186
	20761	Tools for Processing Server Re quests, 27 3
	20762	TOUCH^XUSC LEAN, 312
	20763	Track Pack age Nation ally (KIDS ), 183
	20764	TRANSPORT BUILD NUMB ER Field ( #63), 433
	20765	Transporti ng a Distr ibution (K IDS), 160
	20766	Troublesho oting
	20767	Errors
	20768	KIDS
	20769	Tracking A lpha/Beta Software E rrors, 186
	20770	KIDS
	20771	Tracking A lpha/Beta Software E rrors, 186
	20772	TYPE Field (#4), 212
	20773	Types
	20774	Options, 2 07
	20775	U
	20776	UNCLEAN^XU LMU, 204
	20777	UNWIND^%ZT ER, 100
	20778	Unwinder
	20779	APIs, 461
	20780	Developer Tools, 461
	20781	DISP^XQORM 1, 463
	20782	EN^XQOR, 4 61
	20783	EN^XQORM, 462
	20784	EN1^XQOR, 461
	20785	MSG^XQOR, 462
	20786	XREF^XQORM , 463
	20787	Update ^%Z OSF Nodes, 259
	20788	Update the Status Ba r During P re- and Po st-Install Routines (KIDS), 17 3
	20789	Update wit h Current Routines O ption, 436 , 437
	20790	UPDATE^XPD ID, 190
	20791	UPDCOMP^XL FNAME2, 25 1
	20792	URLs
	20793	Acronyms I ntranet We bsite, 597
	20794	Adobe Webs ite, lxiv
	20795	EPMO Websi te, lxi
	20796	Glossary I ntranet We bsite, 597
	20797	Kernel Web site, lxiv
	20798	VA Softwar e Document Library ( VDL), lxiv
	20799	Usage Repo rts
	20800	Alpha/Beta Tracking (KIDS), 18 7
	20801	Use of
	20802	DIDEL in ^ DIE Calls, 107
	20803	DLAYGO in ^DIC Calls , 107
	20804	DLAYGO Whe n Navigati ng to File s, 106
	20805	USE PARAME TERS, 61
	20806	USE PARAME TERS Field , 64
	20807	Use this M anual, How to, lx
	20808	USE^%ZISUT L, 84
	20809	User
	20810	$$ACTIVE^X USER, 467
	20811	$$CODE2TXT ^XUA4A72, 464
	20812	$$DTIME^XU P, 465
	20813	$$GET^XUA4 A72, 464
	20814	$$IEN2CODE ^XUA4A72, 465
	20815	$$LOOKUP^X USER, 473
	20816	$$NAME^XUS ER, 475
	20817	$$PROVIDER ^XUSER, 47 6
	20818	APIs, 464
	20819	Developer Tools, 464
	20820	DIV4^XUSER , 472
	20821	DIVGET^XUS RB2, 481
	20822	DIVSET^XUS RB2, 481
	20823	USERINFO^X USRB2, 482
	20824	USER CLASS Field (#9 .5), 285
	20825	USER CLASS File (#20 1), 285
	20826	User Inter face
	20827	^%Z Editor , 222
	20828	USER TERMI NATE ROUTI NE Field, 279
	20829	USER TERMI NATE ROUTI NE Option (Obsolete) , 279
	20830	USER TERMI NATE TAG F ield, 279
	20831	User Termi nation Act ion, Creat ing, 279
	20832	USER^XQALE RT, 36
	20833	USERDATA^X QALBUTL, 2 1
	20834	USERINFO^X USRB2, 482
	20835	USERLIST^X QALBUTL, 2 2
	20836	Using Chec kpoints (P re- and Po st-Install Routines) , 176
	20837	Using SYNC FLAGs to Control Se quences of Tasks (Ta skMan), 31 0
	20838	USR CLASS File (#893 0), 400
	20839	Utilities
	20840	%G, 222
	20841	%ZTPP, 432
	20842	^XUP, 184
	20843	^XUS, 184
	20844	Lookup Uti lity
	20845	Miscellane ous Develo per Tools, 226, 227
	20846	PackMan Co mpare, 434
	20847	XINDEX, 42 9, 435, 43 9, 444
	20848	Error Code s, 441, 44 2
	20849	Utility Fu nctions
	20850	$$BASE^XLF UTL, 563
	20851	$$CCD^XLFU TL, 564
	20852	$$CNV^XLFU TL, 564
	20853	$$DEC^XLFU TL, 565
	20854	$$VCD^XLFU TL, 566
	20855	Utility Fu nctions (X LF), 563
	20856	V
	20857	VA FileMan , 573
	20858	VA FileMan lookups a nd MTLU, 3 81
	20859	VA FileMan Supported Calls
	20860	Multi-Term Look-Up ( MTLU), 381
	20861	VA Program ming Stand ards and C onventions (SAC), 43 5, 439
	20862	VA Softwar e Document Library ( VDL)
	20863	Website, l xiv
	20864	valid XML, 573
	20865	Validated Document, 573
	20866	VALIDAV^XU SRB, 294
	20867	Value
	20868	Parameter Tools
	20869	Toolkit AP Is, 401
	20870	Variable C hanger Opt ion, 432
	20871	Variables
	20872	Developer Use in Men u Manager, 208
	20873	DIFROM, 16 6
	20874	DIFROM (KI DS), 172
	20875	KIDS, 166, 172
	20876	Server Opt ions, 273
	20877	Tasks, 303
	20878	XPDENV, 16 6
	20879	XPDNM, 166
	20880	XPDNM (KID S), 172
	20881	XPDNM(”SEQ ”), 166, 1 72
	20882	XPDNM(”TST ”), 166, 1 72
	20883	XQABTST, 1 84
	20884	XQMM(”A”) (Menu Mana ger), 208
	20885	XQMM(”B”) (Menu Mana ger), 208
	20886	XQMM(”J”) (Menu Mana ger), 209
	20887	XQMM(”N”) (Menu Mana ger), 209
	20888	XQUIT (Men u Manager) , 208
	20889	ZTQUEUED ( KIDS), 173
	20890	Verificati on Tools, 435
	20891	^%INDEX Di rect Mode Utility, 4 36
	20892	^%ZTER Dir ect Mode U tility, 43 6
	20893	^nsNTEG Di rect Mode Utility, 4 36
	20894	^XINDEX Di rect Mode Utility, 4 36
	20895	^XTER Dire ct Mode Ut ility, 436
	20896	^XTERPUR D irect Mode Utility, 436
	20897	Calculate and Show C hecksum Va lues Optio n
	20898	Programmer Options M enu, 437, 438
	20899	CHCKSUM ^X TSUMBLD Di rect Mode Utility, 4 35, 437, 4 38
	20900	Direct Mod e Utilitie s, 435
	20901	ONE^nsNTEG Direct Mo de Utility , 436
	20902	Routine Co mpare - Cu rrent with Previous option, 43 6, 437
	20903	Update wit h Current Routines o ption, 437
	20904	Update wit h Current Routines O ption, 436
	20905	Verifier T ools Menu, 436
	20906	Verifying Patch Inst allation ( KIDS), 167
	20907	VERSION Fi eld (#22, Multiple), 191
	20908	Version Nu mber Updat e Option, 432
	20909	Version Nu mbers (KID S), 167
	20910	VHA Unique ID (VUID)
	20911	Toolkit AP Is, 414
	20912	VistA XML Parser
	20913	Introducti on, 573
	20914	VOLUME SET File (#14 .5), 335
	20915	W
	20916	WAIT^ZTMKU Direct Mo de utility , 311
	20917	Websites
	20918	Acronyms I ntranet We bsite, 597
	20919	Adobe Webs ite, lxiv
	20920	EPMO, lxi
	20921	Glossary I ntranet We bsite, 597
	20922	Kernel, lx iv
	20923	VA Softwar e Document Library ( VDL), lxiv
	20924	well forme d XML, 573
	20925	When to Tr ansport Mo re than On e Transpor t Global i n a Distri bution (KI DS), 162
	20926	Where Ques tions Are Asked Duri ng Install ations (KI DS), 176
	20927	WIN^XGF, 4 98
	20928	WITNESS^XU VERIFY, 29 7
	20929	Workday Ca lculation, 227
	20930	Workday Of fset Calcu lation, 23 1
	20931	Workday Va lidation, 230
	20932	World Wide Web Conso rtium (W3C ’s), 573
	20933	Document O bject Mode l (DOM), 5 73
	20934	World Wide Web Conso rtium Docu ment Objec t Model Sp ecificatio n, 573
	20935	Writing Tw o-step Tas ks (TaskMa n)
	20936	Long Runni ng Tasks, 307, 308
	20937	X
	20938	XDR REPOIN TED ENTRY File (#15. 3), 368
	20939	XDRMERG
	20940	EN^XDRMERG , 368
	20941	RESTART^XD RMERG, 370
	20942	XDRMERGB
	20943	SAVEMERG^X DRMERGB, 3 71
	20944	XGF Direct Mode Util ities, 484
	20945	XGF Functi on Library
	20946	$$READ^XGF , 491
	20947	^XGFDEMO, 484
	20948	^XGFDEMO D irect Mode Utility, 484
	20949	APIs, 485
	20950	CHGA^XGF, 485
	20951	CLEAN^XGF, 486
	20952	CLEAR^XGF, 487
	20953	Demo Progr am, 484
	20954	Developer Tools
	20955	Overview, 483
	20956	FRAME^XGF, 488
	20957	INITKB^XGF , 489
	20958	IOXY^XGF, 489
	20959	PREP^XGF, 490
	20960	RESETKB^XG F, 493
	20961	RESTORE^XG F, 493
	20962	SAVE^XGF, 494
	20963	SAY^XGF, 4 95
	20964	SAYU^XGF, 496
	20965	SETA^XGF, 497
	20966	System Req uirements, 483
	20967	WIN^XGF, 4 98
	20968	XGFDEMO
	20969	^XGFDEMO, 484
	20970	XINDEX, 43 6
	20971	XINDEX Uti lity, 429, 435, 439, 444
	20972	Error Code s, 441, 44 2
	20973	XIPUTIL
	20974	$$FIPS^XIP UTIL, 4
	20975	$$FIPSCHK^ XIPUTIL, 5
	20976	CCODE^XIPU TIL, 3
	20977	POSTAL^XIP UTIL, 5
	20978	POSTALB^XI PUTIL, 8
	20979	XLF Functi on Library
	20980	$$%H^XLFDT , 503
	20981	$$ABS^XLFM TH, 529
	20982	$$ACOS^XLF MTH, 530
	20983	$$ACOSDEG^ XLFMTH, 53 0
	20984	$$ACOSH^XL FHYPER, 52 3
	20985	$$ACOT^XLF MTH, 531
	20986	$$ACOTDEG^ XLFMTH, 53 1
	20987	$$ACOTH^XL FHYPER, 52 4
	20988	$$ACSC^XLF MTH, 532
	20989	$$ACSCDEG^ XLFMTH, 53 2
	20990	$$ACSCH^XL FHYPER, 52 4
	20991	$$ASEC^XLF MTH, 533
	20992	$$ASECDEG^ XLFMTH, 53 3
	20993	$$ASECH^XL FHYPER, 52 5
	20994	$$ASIN^XLF MTH, 534
	20995	$$ASINDEG^ XLFMTH, 53 4
	20996	$$ASINH^XL FHYPER, 52 5
	20997	$$ATAN^XLF MTH, 535
	20998	$$ATANDEG^ XLFMTH, 53 5
	20999	$$ATANH^XL FHYPER, 52 6
	21000	$$BASE^XLF UTL, 563
	21001	$$BSA^XLFM SMT, 549
	21002	$$CCD^XLFU TL, 564
	21003	$$CJ^XLFST R, 554
	21004	$$CNV^XLFU TL, 564
	21005	$$CONVERT^ XLFIPV, 56 7
	21006	$$COS^XLFM TH, 536
	21007	$$COSDEG^X LFMTH, 536
	21008	$$COSH^XLF HYPER, 526
	21009	$$COT^XLFM TH, 537
	21010	$$COTDEG^X LFMTH, 537
	21011	$$COTH^XLF HYPER, 527
	21012	$$CRC16^XL FCRC, 500
	21013	$$CRC32^XL FCRC, 502
	21014	$$CSC^XLFM TH, 538
	21015	$$CSCDEG^X LFMTH, 538
	21016	$$CSCH^XLF HYPER, 527
	21017	$$DEC^XLFU TL, 565
	21018	$$DECDMS^X LFMTH, 539
	21019	$$DMSDEC^X LFMTH, 539
	21020	$$DOW^XLFD T, 503
	21021	$$DT^XLFDT , 504
	21022	$$DTR^XLFM TH, 540
	21023	$$E^XLFMTH , 540
	21024	$$EXP^XLFM TH, 541
	21025	$$FMADD^XL FDT, 505
	21026	$$FMDIFF^X LFDT, 505
	21027	$$FMTE^XLF DT, 506
	21028	$$FMTH^XLF DT, 511
	21029	$$FMTHL7^X LFDT, 511
	21030	$$FORCEIP4 ^XLFIPV, 5 68
	21031	$$FORCEIP6 ^XLFIPV, 5 69
	21032	$$HADD^XLF DT, 512
	21033	$$HDIFF^XL FDT, 512
	21034	$$HL7TFM^X LFDT, 513
	21035	$$HTE^XLFD T, 515
	21036	$$HTFM^XLF DT, 517
	21037	$$INVERT^X LFSTR, 555
	21038	$$LENGTH^X LFMSMT, 55 0
	21039	$$LJ^XLFST R, 555
	21040	$$LN^XLFMT H, 541
	21041	$$LOG^XLFM TH, 542
	21042	$$LOW^XLFS TR, 556
	21043	$$MAX^XLFM TH, 542
	21044	$$MIN^XLFM TH, 543
	21045	$$NOW^XLFD T, 517
	21046	$$PI^XLFMT H, 543
	21047	$$PWR^XLFM TH, 544
	21048	$$REPEAT^X LFSTR, 557
	21049	$$REPLACE^ XLFSTR, 55 7
	21050	$$RJ^XLFST R, 558
	21051	$$RTD^XLFM TH, 544
	21052	$$SCH^XLFD T, 518
	21053	$$SEC^XLFD T, 521
	21054	$$SEC^XLFM TH, 545
	21055	$$SECDEG^X LFMTH, 546
	21056	$$SECH^XLF HYPER, 528
	21057	$$SENTENCE ^XLFSTR, 5 59
	21058	$$SIN^XLFM TH, 546
	21059	$$SINDEG^X LFMTH, 547
	21060	$$SINH^XLF HYPER, 528
	21061	$$SQRT^XLF MTH, 547
	21062	$$STRIP^XL FSTR, 559
	21063	$$TAN^XLFM TH, 548
	21064	$$TANDEG^X LFMTH, 548
	21065	$$TANH^XLF HYPER, 529
	21066	$$TEMP^XLF MSMT, 551
	21067	$$TITLE^XL FSTR, 560
	21068	$$TRIM^XLF STR, 561
	21069	$$TZ^XLFDT , 522
	21070	$$UP^XLFST R, 562
	21071	$$VALIDATE ^XLFIPV, 5 70
	21072	$$VCD^XLFU TL, 566
	21073	$$VERSION^ XLFIPV, 57 1
	21074	$$VOLUME^X LFMSMT, 55 2
	21075	$$WEIGHT^X LFMSMT, 55 3
	21076	$$WITHIN^X LFDT, 522
	21077	APIs, 500
	21078	CRC Functi ons, 500
	21079	Date Funct ions, 503
	21080	Developer Tools
	21081	Overview, 500
	21082	Hyperbolic Trigonome tric Funct ions, 523
	21083	IP Address Functions , 567
	21084	Math Funct ions, 529
	21085	Measuremen t Function s, 549
	21086	String Fun ctions, 55 4
	21087	Utility Fu nctions, 5 63
	21088	XLFCRC
	21089	$$CRC16^XL FCRC, 500
	21090	$$CRC32^XL FCRC, 502
	21091	CRC Functi ons, 500
	21092	XLFDT
	21093	$$%H^XLFDT , 503
	21094	$$DOW^XLFD T, 503
	21095	$$DT^XLFDT , 504
	21096	$$FMADD^XL FDT, 505
	21097	$$FMDIFF^X LFDT, 505
	21098	$$FMTE^XLF DT, 506
	21099	$$FMTH^XLF DT, 511
	21100	$$FMTHL7^X LFDT, 511
	21101	$$HADD^XLF DT, 512
	21102	$$HDIFF^XL FDT, 512
	21103	$$HL7TFM^X LFDT, 513
	21104	$$HTE^XLFD T, 515
	21105	$$HTFM^XLF DT, 517
	21106	$$NOW^XLFD T, 517
	21107	$$SCH^XLFD T, 518
	21108	$$SEC^XLFD T, 521
	21109	$$TZ^XLFDT , 522
	21110	$$WITHIN^X LFDT, 522
	21111	Date Funct ions), 503
	21112	XLFHYPER
	21113	$$ACOSH^XL FHYPER, 52 3
	21114	$$ACOTH^XL FHYPER, 52 4
	21115	$$ACSCH^XL FHYPER, 52 4
	21116	$$ASECH^XL FHYPER, 52 5
	21117	$$ASINH^XL FHYPER, 52 5
	21118	$$ATANH^XL FHYPER, 52 6
	21119	$$COSH^XLF HYPER, 526
	21120	$$COTH^XLF HYPER, 527
	21121	$$CSCH^XLF HYPER, 527
	21122	$$SECH^XLF HYPER, 528
	21123	$$SINH^XLF HYPER, 528
	21124	$$TANH^XLF HYPER, 529
	21125	Hyperbolic Trigonome tric Funct ions), 523
	21126	XLFIPV
	21127	$$CONVERT^ XLFIPV, 56 7
	21128	$$FORCEIP4 ^XLFIPV, 5 68
	21129	$$FORCEIP6 ^XLFIPV, 5 69
	21130	$$VALIDATE ^XLFIPV, 5 70
	21131	$$VERSION^ XLFIPV, 57 1
	21132	IP Address Functions ), 567
	21133	XLFMSMT
	21134	$$BSA^XLFM SMT, 549
	21135	$$LENGTH^X LFMSMT, 55 0
	21136	$$TEMP^XLF MSMT, 551
	21137	$$VOLUME^X LFMSMT, 55 2
	21138	$$WEIGHT^X LFMSMT, 55 3
	21139	Measuremen t Function s), 549
	21140	XLFMTH
	21141	$$ABS^XLFM TH, 529
	21142	$$ACOS^XLF MTH, 530
	21143	$$ACOSDEG^ XLFMTH, 53 0
	21144	$$ACOT^XLF MTH, 531
	21145	$$ACOTDEG^ XLFMTH, 53 1
	21146	$$ACSC^XLF MTH, 532
	21147	$$ACSCDEG^ XLFMTH, 53 2
	21148	$$ASEC^XLF MTH, 533
	21149	$$ASECDEG^ XLFMTH, 53 3
	21150	$$ASIN^XLF MTH, 534
	21151	$$ASINDEG^ XLFMTH, 53 4
	21152	$$ATAN^XLF MTH, 535
	21153	$$ATANDEG^ XLFMTH, 53 5
	21154	$$COS^XLFM TH, 536
	21155	$$COSDEG^X LFMTH, 536
	21156	$$COT^XLFM TH, 537
	21157	$$COTDEG^X LFMTH, 537
	21158	$$CSC^XLFM TH, 538
	21159	$$CSCDEG^X LFMTH, 538
	21160	$$DECDMS^X LFMTH, 539
	21161	$$DMSDEC^X LFMTH, 539
	21162	$$DTR^XLFM TH, 540
	21163	$$E^XLFMTH , 540
	21164	$$EXP^XLFM TH, 541
	21165	$$LN^XLFMT H, 541
	21166	$$LOG^XLFM TH, 542
	21167	$$MAX^XLFM TH, 542
	21168	$$MIN^XLFM TH, 543
	21169	$$PI^XLFMT H, 543
	21170	$$PWR^XLFM TH, 544
	21171	$$RTD^XLFM TH, 544
	21172	$$SD^XLFMT H, 545
	21173	$$SEC^XLFM TH, 545
	21174	$$SECDEG^X LFMTH, 546
	21175	$$SIN^XLFM TH, 546
	21176	$$SINDEG^X LFMTH, 547
	21177	$$SQRT^XLF MTH, 547
	21178	$$TAN^XLFM TH, 548
	21179	$$TANDEG^X LFMTH, 548
	21180	Math Funct ions), 529
	21181	XLFNAME
	21182	$$BLDNAME^ XLFNAME, 2 32
	21183	$$CLEANC^X LFNAME, 23 4
	21184	$$FMNAME^X LFNAME, 23 6
	21185	$$HLNAME^X LFNAME, 23 8
	21186	$$NAMEFMT^ XLFNAME, 2 41
	21187	NAMECOMP^X LFNAME, 24 0
	21188	STDNAME^XL FNAME, 245
	21189	XLFNAME2
	21190	DELCOMP^XL FNAME2, 25 0
	21191	UPDCOMP^XL FNAME2, 25 1
	21192	XLFNSLK
	21193	$$ADDRESS^ XLFNSLK, 8 8
	21194	MAIL^XLFNS LK, 89
	21195	XLFSTR
	21196	$$CJ^XLFST R, 554
	21197	$$INVERT^X LFSTR, 555
	21198	$$LJ^XLFST R, 555
	21199	$$LOW^XLFS TR, 556
	21200	$$REPEAT^X LFSTR, 557
	21201	$$REPLACE^ XLFSTR, 55 7
	21202	$$RJ^XLFST R, 558
	21203	$$SENTENCE ^XLFSTR, 5 59
	21204	$$STRIP^XL FSTR, 559
	21205	$$TITLE^XL FSTR, 560
	21206	$$TRIM^XLF STR, 561
	21207	$$UP^XLFST R, 562
	21208	String Fun ctions), 5 54
	21209	XLFUTL
	21210	$$BASE^XLF UTL, 563
	21211	$$CCD^XLFU TL, 564
	21212	$$CNV^XLFU TL, 564
	21213	$$DEC^XLFU TL, 565
	21214	$$VCD^XLFU TL, 566
	21215	Utility Fu nctions), 563
	21216	XML
	21217	$$ATTRIB^M XMLDOM, 57 6
	21218	$$CHILD^MX MLDOM, 577
	21219	$$CMNT^MXM LDOM, 577
	21220	$$EN^MXMLD OM, 579
	21221	$$NAME^MXM LDOM, 580
	21222	$$PARENT^M XMLDOM, 58 0
	21223	$$SIBLING^ MXMLDOM, 5 81
	21224	$$SYMENC^M XMLUTL, 58 8
	21225	$$TEXT^MXM LDOM, 581
	21226	$$VALUE^MX MLDOM, 582
	21227	$$XMLHDR^M XMLUTL, 58 8
	21228	APIs, 576
	21229	CMNT^MXMLD OM, 578
	21230	DELETE^MXM LDOM, 578
	21231	Developer Tools, 576
	21232	EN^MXMLPRS E, 583
	21233	TEXT^MXMLD OM, 582
	21234	XML Docume nt, 586
	21235	XML ENTITY CATALOG ( #950)
	21236	Fields
	21237	.01, 574
	21238	1, 574
	21239	XML ENTITY CATALOG F ile (#950) , 574
	21240	XML Parser
	21241	Known Issu es
	21242	Retrieval of Externa l Entities Using Non -Standard File Acces s Protocol s, 575
	21243	Unsupporte d Characte r Encoding s, 575
	21244	XML Parser
	21245	Known Issu es
	21246	M Limitati ons, 575
	21247	XML Parser
	21248	Usage Exam ple, 586
	21249	XML Parser (VistA)
	21250	APIs, 573, 574
	21251	XML Parser , VistA
	21252	Introducti on, 573
	21253	XPAR
	21254	$$GET^XPAR , 405
	21255	ADD^XPAR, 401
	21256	CHG^XPAR, 402
	21257	DEL^XPAR, 402
	21258	EN^XPAR, 4 03
	21259	ENVAL^XPAR , 404
	21260	GETLST^XPA R, 406
	21261	GETWP^XPAR , 407
	21262	NDEL^XPAR, 408
	21263	PUT^XPAR, 409
	21264	REP^XPAR, 409
	21265	XPAREDIT
	21266	BLDLST^XPA REDIT, 410
	21267	EDIT^XPARE DIT, 410
	21268	EDITPAR^XP AREDIT, 41 0
	21269	EN^XPAREDI T, 411
	21270	GETENT^XPA REDIT, 411
	21271	GETPAR^XPA REDIT, 412
	21272	TED^XPARED IT, 412
	21273	TEDH^XPARE DIT, 413
	21274	XPD BUILD NAMESPACE Option, 14 4
	21275	XPD COPY B UILD Optio n, 145
	21276	XPD INSTAL L BUILD Op tion, 165
	21277	XPD MAIN M enu, 142
	21278	XPD NO_EPP _DELETE Pa rameter, 1 72
	21279	XPDENV Var iable, 166
	21280	XPDID
	21281	EXIT^XPDID , 226
	21282	INIT^XPDID , 225
	21283	TITLE^XPDI D, 225
	21284	UPDATE^XPD ID, 190
	21285	XPDIJ
	21286	EN^XPDIJ, 191
	21287	XPDIP
	21288	$$PKGPAT^X PDIP, 191
	21289	XPDKEY
	21290	$$LKUP^XPD KEY, 270
	21291	$$RENAME^X PDKEY, 270
	21292	DEL^XPDKEY , 269
	21293	XPDMENU
	21294	$$ADD^XPDM ENU, 210
	21295	$$DELETE^X PDMENU, 21 0
	21296	$$LKOPT^XP DMENU, 211
	21297	$$TYPE^XPD MENU, 212
	21298	OUT^XPDMEN U, 211
	21299	RENAME^XPD MENU, 212
	21300	XPDNM Vari able, 166, 172
	21301	XPDNM(”SEQ ”) Variabl e, 166, 17 2
	21302	XPDNM(”TST ”) Variabl e, 166, 17 2
	21303	XPDPROT
	21304	$$ADD^XPDP ROT, 213
	21305	$$DELETE^X PDPROT, 21 4
	21306	$$LKPROT^X PDPROT, 21 5
	21307	$$TYPE^XPD PROT, 217
	21308	FIND^XPDPR OT, 214
	21309	OUT^XPDPRO T, 215
	21310	RENAME^XPD PROT, 216
	21311	XPDUTL
	21312	$$COMCP^XP DUTL, 192
	21313	$$CURCP^XP DUTL, 193
	21314	$$INSTALDT ^XPDUTL, 1 93
	21315	$$LAST^XPD UTL, 194
	21316	$$NEWCP^XP DUTL, 196
	21317	$$OPTDE^XP DUTL, 197
	21318	$$PARCP^XP DUTL, 197
	21319	$$PATCH^XP DUTL, 198
	21320	$$PKG^XPDU TL, 198
	21321	$$PRODE^XP DUTL, 199
	21322	$$RTNUP^XP DUTL, 199
	21323	$$UPCP^XPD UTL, 200
	21324	$$VER^XPDU TL, 200
	21325	$$VERCP^XP DUTL, 201
	21326	$$VERSION^ XPDUTL, 20 1
	21327	BMES^XPDUT L, 192
	21328	MES^XPDUTL , 195
	21329	XQ UNREF’D OPTIONS O ption, 221
	21330	XQ1 Routin e, 209
	21331	XQ12 Routi ne, 278
	21332	XQ92
	21333	NEXT^XQ92, 218
	21334	XQAB ACTUA L OPTION U SAGE Optio n, 187
	21335	XQAB AUTO SEND Optio n, 186, 18 8
	21336	XQAB ERR D ATE/SITE/N UM/ROU/ERR Option, 1 88
	21337	XQAB ERROR LOG SERVE R Option, 185
	21338	XQAB ERROR LOG XMIT Option, 18 5, 186
	21339	XQAB ERROR S LOGGED F ile (#8991 .5), 185
	21340	XQAB LIST LOW USAGE OPTS Optio n, 188
	21341	XQAB MENU Menu, 187
	21342	XQABTST Va riable, 18 4
	21343	XQALBUTL
	21344	$$PENDING^ XQALBUTL, 18
	21345	$$PKGPEND^ XQALBUTL, 19
	21346	AHISTORY^X QALBUTL, 1 3
	21347	ALERTDAT^X QALBUTL, 1 5
	21348	DELSTAT^XQ ALBUTL, 16
	21349	NOTIPURG^X QALBUTL, 1 7
	21350	PTPURG^XQA LBUTL, 20
	21351	RECIPURG^X QALBUTL, 2 0
	21352	USERDATA^X QALBUTL, 2 1
	21353	USERLIST^X QALBUTL, 2 2
	21354	XQALERT
	21355	$$SETUP1^X QALERT, 31
	21356	ACTION^XQA LERT, 22
	21357	DELETE^XQA LERT, 23
	21358	DELETEA^XQ ALERT, 24
	21359	GETACT^XQA LERT, 25
	21360	PATIENT^XQ ALERT, 26
	21361	SETUP^XQAL ERT, 27
	21362	USER^XQALE RT, 36
	21363	XQALFWD
	21364	FORWARD^XQ ALFWD, 37
	21365	XQALSURO
	21366	$$CURRSURO ^XQALSURO, 39
	21367	$$GETSURO^ XQALSURO, 39
	21368	REMVSURO^X QALSURO, 4 0
	21369	SETSURO1^X QALSURO, 4 1
	21370	SUROFOR^XQ ALSURO, 42
	21371	SUROLIST^X QALSURO, 4 3
	21372	XQCHK
	21373	$$ACCESS^X QCHK, 218
	21374	OP^XQCHK, 219
	21375	XQDATE
	21376	^XQDATE, 2 27
	21377	XQH
	21378	EN^XQH, 10 9
	21379	EN1^XQH, 1 09
	21380	XQH4
	21381	ACTION^XQH 4, 110
	21382	XQOR
	21383	EN^XQOR, 4 61
	21384	EN1^XQOR, 461
	21385	MSG^XQOR, 462
	21386	XQORM
	21387	EN^XQORM, 462
	21388	XREF^XQORM , 463
	21389	XQORM1
	21390	DISP^XQORM 1, 463
	21391	XQUIT Vari able, 208
	21392	XREF^XQORM , 463
	21393	XTER Direc t Mode Uti lity, 96
	21394	XTERPUR Di rect Mode Utility, 9 6
	21395	XTFCE, 431
	21396	XTFCR Opti on, 431
	21397	XTHC10
	21398	$$GETURL^X THC10, 372
	21399	XTHCURL
	21400	$$ENCODE^X THCURL, 37 4
	21401	$$MAKEURL^ XTHCURL, 3 75
	21402	$$PARSEURL ^XTHCURL, 376
	21403	XTHCUTL
	21404	$$DECODE^X THCUTL, 37 7
	21405	XTID
	21406	$$GETMASTR ^XTID, 416
	21407	$$GETSTAT^ XTID, 417
	21408	$$GETVUID^ XTID, 419
	21409	$$SCREEN^X TID, 420
	21410	$$SETMASTR ^XTID, 422
	21411	$$SETSTAT^ XTID, 423
	21412	$$SETVUID^ XTID, 425
	21413	GETIREF^XT ID, 414
	21414	XTIDTRM
	21415	$$GETRPLC^ XTIDTRM, 3 48
	21416	$$RPLCLST^ XTIDTRM, 3 49
	21417	$$RPLCMNT^ XTIDTRM, 3 50
	21418	$$RPLCTRL^ XTIDTRM, 3 51
	21419	$$RPLCVALS ^XTIDTRM, 352
	21420	$$SETRPLC^ XTIDTRM, 3 53
	21421	XTKERM4
	21422	RFILE^XTKE RM4, 378
	21423	XTKERMIT
	21424	RECEIVE^XT KERMIT, 37 8
	21425	SEND^XTKER MIT, 379
	21426	XTLKKWL
	21427	XTLKKWL^XT LKKWL, 382
	21428	XTLKKWL^XT LKKWL, 382
	21429	XTLKMGR
	21430	DK^XTLKMGR , 383
	21431	DLL^XTLKMG R, 383
	21432	DSH^XTLKMG R, 384
	21433	DSY^XTLKMG R, 384
	21434	K^XTLKMGR, 385
	21435	L^XTLKMGR, 385
	21436	LKUP^XTLKM GR, 386
	21437	SH^XTLKMGR , 390
	21438	SY^XTLKMGR , 391
	21439	XTMP Globa l, 160, 16 1, 168, 26 3, 264, 29 5, 296, 30 7
	21440	XTMUNIT GR OUP EDIT O ption, 392
	21441	XTMUNIT GR OUP RUN Op tion, 392
	21442	XTMUNIT Ro utine, 394 , 395
	21443	XT-OPTION TEST Optio n, 222
	21444	XTRCMP Rou tine, 433, 434
	21445	XTRDEL Opt ion, 434
	21446	XTRGRPE Op tion, 431
	21447	XT-ROUTINE COMPARE O ption, 434
	21448	XTSUMBLD-C HECK Optio n
	21449	Programmer Options M enu, 437, 438
	21450	XTV Global , 184
	21451	XTV MENU M enu, 436
	21452	XTV ROUTIN E CHANGES File (#899 1), 437
	21453	XT-VARIABL E CHANGER Option, 43 2
	21454	XTVCHG Rou tine, 432
	21455	XT-VERSION NUMBER Op tion, 432
	21456	XTVNUM Rou tine, 432
	21457	XTVR COMPA RE Option, 436, 437
	21458	XTVR UPDAT E Option, 436, 437
	21459	XU BLOCK C OUNT Optio n, 221, 25 9
	21460	XU CHECKSU M LOAD Opt ion, 434
	21461	XU CHECKSU M REPORT O ption, 433 , 438
	21462	XU Namespa ce, 187
	21463	XU SID ASK Option, 2 83
	21464	XU SID STA RTUP Optio n, 283
	21465	XU USER SI GN-ON Exte nded Actio n, 284
	21466	XU USER SI GN-ON Opti on, 277
	21467	Package-sp ecific Sig non Action s, 277
	21468	XU USER ST ART-UP Opt ion, 278
	21469	Package-sp ecific Sig non Action s, 278
	21470	XU USER TE RMINATE Op tion, 279
	21471	XUA4A71
	21472	$$EN^XUA4A 71, 226
	21473	XUA4A72
	21474	$$CODE2TXT ^XUA4A72, 464
	21475	$$GET^XUA4 A72, 464
	21476	$$IEN2CODE ^XUA4A72, 465
	21477	XUAF4
	21478	$$ACTIVE^X UAF4, 121
	21479	$$CIRN^XUA F4, 122
	21480	$$ID^XUAF4 , 124
	21481	$$IDX^XUAF 4, 124
	21482	$$IEN^XUAF 4, 125
	21483	$$LEGACY^X UAF4, 125
	21484	$$LKUP^XUA F4, 126
	21485	$$MADD^XUA F4, 127
	21486	$$NAME^XUA F4, 127
	21487	$$NNT^XUAF 4, 128
	21488	$$NS^XUAF4 , 128
	21489	$$O99^XUAF 4, 129
	21490	$$PADD^XUA F4, 129
	21491	$$PRNT^XUA F4, 130
	21492	$$RF^XUAF4 , 131
	21493	$$RT^XUAF4 , 131
	21494	$$STA^XUAF 4, 133
	21495	$$TF^XUAF4 , 133
	21496	$$WHAT^XUA F4, 134
	21497	CDSYS^XUAF 4, 121
	21498	CHILDREN^X UAF4, 122
	21499	F4^XUAF4, 123
	21500	LOOKUP^XUA F4, 126
	21501	PARENT^XUA F4, 130
	21502	SIBLING^XU AF4, 132
	21503	XUDHGUI
	21504	DEVICE^XUD HGUI, 55
	21505	XUDHSET
	21506	$$RES^XUDH SET, 58
	21507	XUEDITOPT Option, 20 7
	21508	XUHUI
	21509	OPKG^XUHUI , 101
	21510	XUINDEX Op tion, 429, 444
	21511	XUKERNEL M enu, 189, 283
	21512	XULMU
	21513	ADDPAT^XUL MU, 205
	21514	CLEANUP^XU LMU, 202
	21515	PAT^XULMU, 205
	21516	SETCLEAN^X ULMU, 203
	21517	UNCLEAN^XU LMU, 204
	21518	XUMF
	21519	$$IEN^XUMF , 134
	21520	XUMFI
	21521	MAIN^XUMFI , 135
	21522	XUMFP
	21523	MAIN^XUMFP , 136
	21524	XUMGR Secu rity Key, 222
	21525	XUP
	21526	$$DTIME^XU P, 465
	21527	^XUP Direc t Mode Uti lity, 276
	21528	XUP Routin e, 209
	21529	XUP Utilit y, 184
	21530	XUPARAM
	21531	$$GET^XUPA RAM, 280
	21532	$$KSP^XUPA RAM, 281
	21533	$$LKUP^XUP ARAM, 282
	21534	SET^XUPARA M, 282
	21535	XUPR RTN E DIT, 432
	21536	XUPR RTN P ATCH Optio n, 432
	21537	XUPRGL Opt ion, 222
	21538	XUPROD
	21539	$$PROD^XUP ROD, 283
	21540	XUPROG Men u, 142, 42 8, 437, 44 4
	21541	XUPROG Sec urity Key, 142, 222, 428, 434, 444
	21542	XUPROGMODE Security Key, 222, 428, 431, 432, 434, 438
	21543	XUPRROU Op tion, 432
	21544	XUPR-ROUTI NE-TOOLS M enu, 428, 444
	21545	XUPR-RTN-T APE-CMP Op tion, 433
	21546	XUPS
	21547	$$IEN^XUPS , 45
	21548	$$VPID^XUP S, 45
	21549	XUPS PERSO NQUERY RPC , 46
	21550	XUPSQRY
	21551	EN1^XUPSQR Y, 46
	21552	XUROUTINE IN Options , 434
	21553	XUROUTINE OUT Option , 434
	21554	XUS
	21555	^XUS Direc t Mode Uti lity, 276
	21556	H^XUS, 283
	21557	H^XUS Dire ct Mode Ut ility, 277
	21558	XUS KEY CH ECK RPC, 2 71
	21559	XUS Utilit y, 184
	21560	XUS1A
	21561	SET^XUS1A, 284
	21562	XUS2
	21563	AVHLPTXT^X US2, 284
	21564	XUSCLEAN
	21565	$$CREATE^X USAP, 285
	21566	^XUSCLEAN Direct Mod e Utility, 277
	21567	KILL^XUSCL EAN, 289
	21568	TOUCH^XUSC LEAN, 312
	21569	XUSEC Glob al, 269, 2 70
	21570	XUSER
	21571	$$ACTIVE^X USER, 467
	21572	$$DEA^XUSE R, 468
	21573	$$LOOKUP^X USER, 473
	21574	$$NAME^XUS ER, 475
	21575	$$PROVIDER ^XUSER, 47 6
	21576	$$SDEA^XUS ER, 477
	21577	$$SDETOX^X USER, 471
	21578	$$VDEA^XUS ER, 479
	21579	DIV4^XUSER , 472
	21580	XUSERNEW
	21581	$$ADD^XUSE RNEW, 290
	21582	XUSESIG
	21583	^XUSESIG, 90
	21584	SIG^XUSESI G, 90
	21585	XUSESIG1
	21586	$$CHKSUM^X USESIG1, 9 1
	21587	$$CMP^XUSE SIG1, 91
	21588	$$DE^XUSES IG1, 92
	21589	$$EN^XUSES IG1, 92
	21590	$$ESBLOCK^ XUSESIG1, 92
	21591	XUSHSH
	21592	$$AESDECR^ XUSHSH, 48
	21593	$$AESENCR^ XUSHSH, 49
	21594	$$B64DECD^ XUSHSH, 50
	21595	$$B64ENCD^ XUSHSH, 50
	21596	$$RSADECR^ XUSHSH, 51
	21597	$$RSAENCR^ XUSHSH, 52
	21598	$$SHAHASH^ XUSHSH, 53
	21599	XUSHSHP
	21600	DE^XUSHSHP , 93
	21601	EN^XUSHSHP , 94
	21602	HASH^XUSHS HP, 94
	21603	XUSITEMGR Menu, 187
	21604	XUSITEPARM Option, 1 89
	21605	XUSNPI
	21606	$$CHKDGT^X USNPI, 254
	21607	$$NPI^XUSN PI, 255
	21608	$$QI^XUSNP I, 256
	21609	XUSPF200 K ey, 290
	21610	XUSRB
	21611	$$CHECKAV^ XUSRB, 291
	21612	$$INHIBIT^ XUSRB, 292
	21613	$$KCHK^XUS RB, 480
	21614	CVC^XUSRB, 292
	21615	INTRO^XUSR B, 293
	21616	LOGOUT^XUS RB, 293
	21617	OWNSKEY^XU SRB, 271
	21618	SETUP^XUSR B, 293
	21619	VALIDAV^XU SRB, 294
	21620	XUSRB1
	21621	$$DECRYP^X USRB1, 294
	21622	$$ENCRYP^X USRB1, 295
	21623	XUSRB2
	21624	DIVGET^XUS RB2, 481
	21625	DIVSET^XUS RB2, 481
	21626	USERINFO^X USRB2, 482
	21627	XUSRB4
	21628	$$HANDLE^X USRB4, 295
	21629	XUSTAX
	21630	$$TAXIND^X USTAX, 257
	21631	$$TAXORG^X USTAX, 258
	21632	XUTL Globa l, 463
	21633	XUTMDEVQ
	21634	$$DEV^XUTM DEVQ, 312
	21635	$$NODEV^XU TMDEVQ, 31 6
	21636	$$QQ^XUTMD EVQ, 318
	21637	$$REQQ^XUT MDEVQ, 321
	21638	EN^XUTMDEV Q, 314
	21639	XUTMOPT
	21640	DISP^XUTMO PT, 322
	21641	EDIT^XUTMO PT, 323
	21642	OPTSTAT^XU TMOPT, 323
	21643	RESCH^XUTM OPT, 324
	21644	XUTMTP
	21645	EN^XUTMTP, 324
	21646	XUVERIFY
	21647	$$CHECKAV^ XUVERIFY, 297
	21648	^XUVERIFY, 296
	21649	WITNESS^XU VERIFY, 29 7
	21650	XUWORKDY
	21651	$$EN^XUWOR KDY, 229
	21652	$$WORKDAY ^XUWORKDY, 230
	21653	$$WORKPLUS ^XUWORKDY , 231
	21654	^XUWORKDY, 227
	21655	Z
	21656	ZIS
	21657	$$REWIND^% ZIS, 70
	21658	^%ZIS, 58
	21659	HLP1^%ZIS, 68
	21660	HLP2^%ZIS, 69
	21661	HOME^%ZIS, 69
	21662	ZISC
	21663	^%ZISC, 71
	21664	ZISH
	21665	$$DEFDIR^% ZISH, 112
	21666	$$DEL^%ZIS H, 113
	21667	$$FTG^%ZIS H, 114
	21668	$$GATF^%ZI SH, 115
	21669	$$GTF^%ZIS H, 116
	21670	$$LIST^%ZI SH, 116
	21671	$$MV^%ZISH , 117
	21672	$$PWD^%ZIS H, 119
	21673	$$STATUS^% ZISH, 119
	21674	CLOSE^%ZIS H, 112
	21675	OPEN^%ZISH , 118
	21676	ZISP
	21677	PKILL^%ZIS P, 71
	21678	PSET^%ZISP , 72
	21679	ZISPL
	21680	DSD^ZISPL, 300
	21681	DSDOC^ZISP L, 300
	21682	ZISS
	21683	ENDR^%ZISS , 73
	21684	ENS^%ZISS, 74
	21685	GKILL^%ZIS S, 78
	21686	GSET^%ZISS , 78
	21687	KILL^%ZISS , 79
	21688	ZISTCP
	21689	CALL^%ZIST CP, 79
	21690	CLOSE^%ZIS TCP, 80
	21691	ZISUTL
	21692	CLOSE^%ZIS UTL, 81
	21693	OPEN^%ZISU TL, 81
	21694	RMDEV^%ZIS UTL, 83
	21695	SAVDEV^%ZI SUTL, 84
	21696	USE^%ZISUT L, 84
	21697	ZOSV
	21698	$$ACTJ^%ZO SV, 262
	21699	$$AVJ^%ZOS V, 263
	21700	$$EC^%ZOSV , 96
	21701	$$LGR^%ZOS V, 264
	21702	$$OS^%ZOSV , 265
	21703	$$VERSION^ %ZOSV, 268
	21704	DOLRO^%ZOS V, 263
	21705	GETENV^%ZO SV, 264
	21706	GETPEER^%Z OSV, 298
	21707	LOGRSRC^%Z OSV, 264
	21708	SETENV^%ZO SV, 265
	21709	SETNM^%ZOS V, 266
	21710	T0^%ZOSV, 266
	21711	T1^%ZOSV, 267
	21712	ZRTL Globa l
	21713	Obsolete, 267, 268
	21714	ZSTOP, 304
	21715	ZTER
	21716	$$NEWERR^% ZTER, 99
	21717	^%ZTER, 97
	21718	UNWIND^%ZT ER, 100
	21719	ZTLOAD, 87
	21720	$$ASKSTOP^ %ZTLOAD, 3 33
	21721	$$JOB^%ZTL OAD, 336
	21722	$$S^%ZTLOA D, 343
	21723	$$TM^%ZTLO AD, 345
	21724	^%ZTLOAD, 325
	21725	DESC^%ZTLO AD, 333
	21726	DQ^%ZTLOAD , 334
	21727	ISQED^%ZTL OAD, 334
	21728	KILL^%ZTLO AD, 336
	21729	OPTION^%ZT LOAD, 337
	21730	PCLEAR^%ZT LOAD, 337
	21731	REQ^%ZTLOA D, 338
	21732	RTN^%ZTLOA D, 342
	21733	STAT^%ZTLO AD, 343
	21734	ZTSAVE^%ZT LOAD, 345
	21735	ZTMB Direc t Mode Uti lity, 311
	21736	ZTMCHK Dir ect Mode U tility, 31 1
	21737	ZTMGRSET R outine, 22 2
	21738	ZTMON Dire ct Mode Ut ility, 311
	21739	ZTMQUEUABL E OPTIONS Menu, 186
	21740	ZTQUEUED v ariable, 3 06
	21741	ZTQUEUED V ariable, 1 73, 304
	21742	ZTREQ, 306
	21743	ZTREQ vari able, 304
	21744	ZTREQ Vari able, 305
	21745	ZTSAVE^%ZT LOAD, 345
	21746	ZTSTAT Var iable, 310
	21747	ZTSTOP Var iable, 304 , 305
	21748	ZU
	21749	^ZU Direct Mode Util ity, 277
	21750
	21751