Print Page as PDF
XQALSURO ICR (3213)

XQALSURO    ICR (3213)

Name Value
NUMBER 3213
IA # 3213
DATE CREATED 2000/09/27
CUSTODIAL PACKAGE KERNEL
CUSTODIAL ISC San Francisco
USAGE Supported
TYPE Routine
DBIC APPROVAL STATUS APPROVED
ROUTINE XQALSURO
NAME XQALSURO
GENERAL DESCRIPTION
This integration agreement adds two additional
SUPPORTED entry points or APIs to XQALSURO.

SETSURO1 should be used in the future instead of SETSURO to establish a
surrogate for alerts.  SETSURO1 returns a value of 1 if the surrogate was
created successfully, otherwise, it returns a text string explaining why the
surrogate was not created.  SETSURO simply added the specified surrogate, but
did not test for cyclic relationships (such that the user eventually would
become the surrogate).  SETSURO1 does these tests and therefore has the
possibility of failure.

GETSURO is an API which can be used to obtain information about the current
surrogate, including start and end date/times if they are specified.

SUROLIST is an API which can be used to obtain a list of the current and
future surrogate periods for a selected user.

SUROFOR is an API which can be used to obtain a list of any current users that
the selected user is acting as a surrogate for.
STATUS Active
KEYWORDS
  • ALERT
  • ALERTS
  • SURROGATE
  • API
ID XQALSURO
COMPONENT/ENTRY POINT
COMPONENT/ENTRY POINT COMPONENT DESCRIPTION VARIABLES
GETSURO
$$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.
VARIABLES TYPE VARIABLES DESCRIPTION
XQAUSER Input
This is the internal entry number in the NEW PERSON
file (file #200) of the user for which alert surrogate information is to be
returned.
SETSURO1
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.
VARIABLES TYPE VARIABLES DESCRIPTION
XQAUSER Input
XQAUSER is the internal entry number in file 200
(DUZ) for the user for which the surrogate should act in receiving alerts.
XQASURRO Input
XQASURRO is the internal entry number in file 200
(DUZ) for the user who will receive and process alerts for XQAUSER.
XQASTART Input
XQASTART is an optional START Date/Time for the
surrogate activity in Filemanager format.  If XQASTART is not specified, the
surrogate relationship begins immediately.
XQAEND Input
XQAEND is an optional date/time for the end of the
surrogate relationship in Filemanager format.  If XQAEND is not specified, the
surrogate remains active until anothersurrogate is specified, or the surrogate
deleted.
SUROLIST
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
VARIABLES TYPE VARIABLES DESCRIPTION
XQAUSER Input
XQAUSER is the internal entry number in file 200
(DUZ) for the user for which the surrogate should act in receiving alerts.
XQALIST Both
XQALIST is a variable which is passed by reference
which will contain the list of current and future surogates for the specified
user.
SUROFOR
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
VARIABLES TYPE VARIABLES DESCRIPTION
XQAUSER Input
XQAUSER is the internal entry number in file 200
(DUZ) for the user for which the surrogate should act in receiving alerts.
XQALIST Both
XQALIST is a variable which is passed by reference
which will contain the list of  users for whom the specified user is currently
acting as a surrogate. The date in the list includes the internal entry number
(DUZ) for the user, the user's name, and the start and end dates for the
surrogate period.
CREATOR IVEY,JOEL
DBA Comments
reactivated 7.29.09
DATE ACTIVATED 2009/07/29
MAIL MESSAGE 32068253
DATE/TIME EDITED
DATE/TIME EDITED ACTION AT THE REQUEST OF
2009/07/28 16:07 DEACTIVATED FOR EDITS IVEY,JOEL
2009/07/29 12:07 APPROVED IVEY,JOEL
Generated from AUG 12, 2020@ IA Listing Descriptions