XQALSURO    ICR (3213)

$$GETSURO^XQALSURO(XQAUSER) returns a string of '^'
separated information on the current surrogate for the user with XQAUSER as
his internal entry number in the NEW PERSON file.  The value returned is of
the form

ien^NAME^FM_STARTDATE^FM_ENDDATE

where ien is the internal entry number of the SURROGATE in the NEW PERSON
file, NAME is the contents of the .01 field for the SURROGATE, FM_STARTDATE is
the starting date/time for the SURROGATE in internal Filemanager format, and
FM_ENDDATE is the ending date/time for the SURROGATE in internal Filemanager
format.

S X=$$GETSURO^XQALSURO(124)

might yield a value of X containing

2327^DOE,JOHN^3000929.1630^3001006.0800

indicating that user #2327 (John Doe) will become active as surrogate at 4:30
PM 9/29/00 and will remain surrogate until 8:00 am on 10/06/00.

If there was no surrogate, the result would be
^^^

If either of the date/times are not specified, they will return a null value
for that piece of the return string.

This API should be used instead of the
SETSURO^XQALSURO API.  The SETSURO1 entry point returns a value indicating
success (a TRUE (value =1)) or failure (a FALSE (value=message indicating
reason for failure)).  The SETSURO entry point returned no value and, as long
as both a user and surrogate were specified, would simply store the values.
This leaves open the possibility that the user is specified as the surrogate
or that a chain of surrogates ends up pointing again at the user, cases that
could result in a very tight, non-ending, loop being generated if an alert was
sent.  These possibilities have been tested for in the interactive
specifiction of surrogates, and is tested for non-interactive usage in the
SETSURO1^XQALSURO API.

Usage would be:

S XQAUSER=DUZ ; user identification
S XQASURO=45 ; Surrogate's DUZ number (internal entry number in file 200)
S XQASTRT=3001004.1630 ; Start Date/Time in Filemanager internal format
S XQAEND=3001008.1630 ; End Date/Time for surrogate in FM internal format
S X=$$SETSURO1^XQALSURO(USER,SURROGAT,START,END)
I 'X W !,"Could not activate surrogate",!,?5,X Q

The Start and End Date/Time values are optional.  If the Start Date/Time is
not specified, the surrogate relationship begins immediately.  If the End
Date/Time is not specified, the surrogate remains active until another
surrogate is specified, or the surrogate deleted.

The SUROLIST entry point returns a returns for
XQAUSER a list of current and/or future surrogates in XQALIST (which must be
passed by reference)

Usage would be:

S XQAUSER=DUZ ; user identification
D SUROLIST^XQALSURO(XQAUSER,.USERLIST)

This returns

USERLIST=count
USERLIST(1)=IEN2^NEWPERSON,USER2^STARTDATETIME^ENDDATETIME
USERLIST(2)=3^NAME,USER3^3050407.1227^3050406

The SUROFOR entry point returns a list of users for
which the specified user is currently acting as a surogate for.

Usage would be:

S XQAUSER=DUZ ; user identification
D SUROFOR^XQALSURO(XQAUSER,.USERLIST)

This returns
USERLIST=count
USERLIST(1)=IEN2^NEWPERSON,USER2^STARTDATETIME^ENDDATETIME
USERLIST(2)=3^NAME,USER3^3050407.1227^3050406