Print Page as PDF
SUPPORTED PARAMETER TOOL ENTRY POINTS ICR (2263)

SUPPORTED PARAMETER TOOL ENTRY POINTS    ICR (2263)

Name Value
NUMBER 2263
IA # 2263
DATE CREATED 1998/01/11
CUSTODIAL PACKAGE TOOLKIT
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE XPAR
NAME SUPPORTED PARAMETER TOOL ENTRY POINTS
GENERAL DESCRIPTION
Parameter Tools is a generic method of handling
parameter definition, assignment, and retrieval.  A parameter may be defined
for various entities where an entity is the level at which you want to allow
the parameter defined (e.g. package level, system level, division level,
location level, user level, etc.).  A developer may then determine in which
order the values assigned to given entities are interpreted.  The following
are some basic definitions used by Parameter Tools:

Entity:
=======
An entity is a level at which you can define a parameter.  The entities
allowed are stored in the Parameter Entity file (#8989.518).  The list of
allowable entities at the time this utility was released were:

Prefix          Message         Points to File
-------         ----------      ------------------------
PKG             Package         Package (9.4)
SYS             System          Domain (4.2)
DIV             Division        Institution (4)
SRV             Service         Service/Section (49)
LOC             Location        Hospital Location (44)
TEA             Team            Team (404.51)
CLS             Class           Usr Class (8930)
USR             User            New Person (200)
BED             Room-Bed        Room-Bed (405.4)
OTL             Team (OE/RR)    OE/RR List (101.21)

(Note:  entries will be maintained via ToolKit patches.  Entries
existing in the file at the time it is referenced are
considered supported.)

Parameter:
==========
A parameter is the actual name which values are stored under.  The name
of the parameter must be namespaced and it must be unique.  Parameters
can be defined to store the typical package parameter data (e.g. the
default add order screen in OE/RR), but they can also be used to store
GUI application screen settings a user has selected (e.g. font or window
width).  When a parameter is defined, the entities which may set that
parameter are also defined.  The definition of parameters is stored in
the PARAMETER DEFINITION file (#8989.51).

Value:
======
A value may be assigned to every parameter for the entities allowed in
the parameter definition.  Values are stored in the PARAMETERS file
(#8989.5).

Instance:
=========
Most parameters will set instance to 1.  Instances are used when more
than one value may be assigned to a given entity/parameter combination.
An example of this would be lab collection times at a division.  A single
division may have multiple collection times.  Each collection time would
be assigned a unique instance.

Parameter Template:
===================
A parameter template is similar to an input template.  It contains a list
of parameters that can be entered through an input session (e.g. option).
Templates are stored in the Parameter Template file (#8989.52).  Entries
in this file must also be namespaced.


This integration agreement defines the callable entry points in routine XPAR.

STATUS Active
DURATION Till Otherwise Agreed
ID XPAR
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
EN(Entity,Parameter,Instance,Value,.Error)
This entry point will:
1) add the value as a new entry to the Parameters file if the
Entity/Parameter/Instance combination does not already exist.
2) change the value assigned to the parameter if the
Entity/Parameter/Instance combination already exists.  or 3) delete the
parameter instance if the value assigned is "@".
VARIABLES TYPE VARIABLES DESCRIPTION
Entity Input
REQUIRED

The entity may be set to:
1) the internal variable pointer (nnn;GLO(123,)
2) the external format of the variable pointer using the 3 character
prefix (prefix.entryname) or 3) the prefix alone to set the parameter
based on current entity
selected.  This will work for the following entities:
"USR" - uses current value of DUZ
"DIV" - uses current value of DUZ(2)
"SYS" - uses system (domain)
"PKG" - uses the package to which the parameter belongs
Parameter Input
REQUIRED

Identifies the name or internal entry number of the parameter as defined in
the PARAMETER DEFINITION file (#8989.51).
Instance Input
OPTIONAL (defaults to 1 if not passed in)

May be passed in external or internal format.  Internal format requires that
the value be preceded by the ` character).
Value Input
REQUIRED

May be passed in external or internal format.  If using internal format for a
pointer type parameter, the value must be preceded with the ` character.).

If the value is being assigned to a word processing parameter, the text may be
passed in the subordinate nodes of Value (e.g. Value(1,0)=Text) and the
variable Value itself may be defined as a title or description of the text.
Error Output
OPTIONAL

If used, must be passed in by reference.  It will return any error condition
which may occur.  If no error occurs, the value assigned will be 0 (zero).  If
an error does occur, it will be in the format: "#^errortext".
ADD(Entity,Parameter,Instance,Value,.Error)
This entry point can be called to add a new parameter
value.  For definition of input and output variables, see component EN
description.
VARIABLES TYPE
Entity Input
Parameter Input
Instance Input
Value Input
Error Output
CHG(Entity,Parameter,Instance,Value,.Error)
This entry point can be called to change an existing
parameter value.  For definition of input and output variables, see component
EN description.
VARIABLES TYPE
Entity Input
Parameter Input
Instance Input
Value Input
Error Output
DEL(Entity,Parameter,Instance,.Error)
This entry point can be called to delete an existing
parameter value.  For definition of input and output variables, see component
EN description.
VARIABLES TYPE
Entity Input
Parameter Input
Instance Input
Error Output
NDEL(Entity,Parameter,.Error)
This entry point can be called to delete the value
for all instances of a parameter for a given entity.  For definition of input
and output variables, see component EN description.
REP(Entity,Parameter,CurrentInstance,NewInstance,.Error)
This entry point will allow a developer to replace
the value of an instance with another value.
VARIABLES TYPE VARIABLES DESCRIPTION
Entity Input
See EN^XPAR component for description.
Parameter Input
See EN^XPAR component for description.
CurrentInstance Input


The instance for which the value is currently defined.
NewInstance Input
REQUIRED

The instance for which you want to assign the value currently assigned to
CurrentInstance.
Error Output
See EN^XPAR component for description.
$$GET(Entity,Parameter,Instance,Format)
This call will allow you to retrieve the value of a
parameter.  The value is returned from this extrinsic function in the format
defined by the variable Format (see below).
VARIABLES TYPE VARIABLES DESCRIPTION
Entity Input
Entity is defined as the single entity or group of
entities you want to look at in order to retrieve the value.  Entities may be
passed in internal or external format (e.g. LOC.PULMONARY or LOC.'57 or
57;SC().  The list of entities in this variable may be defined as follows:

1) a single entity to look at (e.g. LOC.PULMONARY).
2) the word "ALL" which will tell the utility to look for values
assigned to the parameter using the entity precedence defined in the
PARAMETER DEFINITION file.
3) A list of entities you want to search (e.g. "USR^LOC^SYS^PKG").  The
list is searched from left to right with the first value found
returned.
4) Items 2 or 3 with specific entity values referenced such as:
ALL^LOC.PULMONARY - to look at the defined entity precedence, but
when looking at location, only look at the PULMONARY location.
USR^LOC.PULMONARY^SYS^PKG - to look for values for all current
user, PULMONARY location, system, or package).
Parameter Input
REQUIRED

Identifies the name or internal entry number of the parameter as defined in
the PARAMETER DEFINITION file (#8989.51).
Instance Input
OPTIONAL (defaults to 1 if not passed in)

May be passed in external or internal format.  Internal format requires that
the value be preceded by the ` character).
Format Input
OPTIONAL - defaults to "Q" if not defined

Format determines how the value is returned.  It can be set to the following:

1)  "Q" - returns the value in the quickest manner - internal format
2)  "E" - returns external value
3)  "I" - returns internal value
4)  "B" - returns internal^external value

GETLST(.List,Entity,Parameter,Format,.Error[,gbl])
This entry point is similar to $$GET^XPAR, but this
will return ALL instances of a parameter.
VARIABLES TYPE VARIABLES DESCRIPTION
List Output
The array passed as List will be returned with all of
the possible values assigned to the parameter. See variable description for
Format to see how this data can be returned.

If the parameter gbl is set to one, Then this parameter becomes a input and
holds the closed root of a global where GETLST should put the output.  e.i.
$NA(^TMP($J,"XPAR")).
Entity Input
See description of this variable under $$GET
component.
Parameter Input
See description of this variable under $$GET
component.
Error Output
Returns 0 if no error was encountered or returns an
error code in the format #^errortext.
Format Input
This variable defines how the data is returned from
this call.  The data will be returned in the array specified by the variable
List. Possible values for Format are:

1) "Q"    List(#)=internal instance^internal value
2) "I"    List(internal instance)=internal value
3) "E"    List(#)=external instance^external value
4) "B"    List(#,"N")=internal instance^external instance
List(#,"V")="internal value^external value
5) "N"    List(external instance)=internal value^external value

gbl Input
If this optional variable is set to 1.  Then the
parameter List must be set before the call to the closed global root where the
return data should be put.

e.i. GETLST^XPAR($NA(^TMP($J)),ent,par,fmt,.error,1)
GETWP(.ReturnedText,Entity,Parameter,Instance,.Error)
This call returns word processing text in
ReturnedText.  ReturnedText itself contains the value field, which is free
text that may contain a title, description, etc.  The word processing text is
returned in ReturnedText(#,0).
VARIABLES TYPE VARIABLES DESCRIPTION
ReturnedText Both
This variable is defined as the name of an array in
which you want the text returned.  .ReturnedText will be set to the title,
description, etc.  The actual word processing text will be returned in
ReturnedText(#,0).  Example:

ReturnedText="Select Notes Help"
ReturnedText(1,0)="To select a progress note from the list, "
ReturnedText(2,0)="click on the date/title of the note."
Entity Input
See description of variable under $$GET call.
Parameter Input
See description of variable under $$GET call.
Instance Input
See description of variable under $$GET call.
Error Output
See description of this variable under the GETLST
component.
ENVAL(.List,Parameter,Instance,.Error[,gbl])
This entry point will return all parameter instances.
See GETLST and $$GET for a definition of input and output variables to this
call.
VARIABLES TYPE VARIABLES DESCRIPTION
List Output
If the parameter gbl is set to one, Then this
parameter becomes a input and holds the closed root of a global where GETLST
should put the output.  e.i. $NA(^TMP($J,"XPAR")).
Parameter Input
(required) See description of variable under
EN^XPAR() call.

Instance Input
(required) See description of variable under
EN^XPAR() call.

Error Output
(optional) See description of variable under
EN^XPAR() call.

gbl Input
If this optional variable is set to 1.  Then the
parameter List must be set before the call to the closed global root where the
return data should be put.

e.i. S LIST=$NA(^TMP($J)) ENVAL^XPAR(LIST,par,inst,.error,1)
PUT(Entity,Parameter,Instance,Value,.Error)
This entry point can be called to add or update a
parameter instance and bypass the input transforms.

VARIABLES TYPE VARIABLES DESCRIPTION
Entity Input
(required) See description of variable under
EN^XPAR() call.


Parameter Input
(required) See description of variable under
EN^XPAR() call.


Instance Input
(optional) See description of variable under
EN^XPAR() call.


Value Input
(required) See description of variable under
EN^XPAR() call.

Error Output
(optional) See description of variable under
EN^XPAR() call.

DATE ACTIVATED 2012/11/09