PUTDATA

Solved a problem in an elegant manner and want to show off your code? Know a hard-to-find feature? Post it here for the benefit of others. Questions don't belong here.
Post Reply
revellbikes
Posts: 428
Joined: Fri Jun 15, 2012 12:44 pm
Has thanked: 11 times
Been thanked: 43 times

PUTDATA

Post by revellbikes » Mon May 15, 2017 10:09 am

Does anyone have a working example for the PUTDATA command or know the manual it's documented in?

Thanks

steve
Posts: 384
Joined: Wed Nov 30, 2011 10:20 pm
Been thanked: 77 times

Re: PUTDATA

Post by steve » Mon May 15, 2017 10:35 am

Hi,
it's used in RTA portal code

PUTDATA( caseref , {field.type} , value )

where:
caseref is a field or variable containing the case reference that you wish to put data into
{field.type} is the usual name and datatype of the field you wish to update
value is the value that you want to put into the field. Alpha fields need double "" surrounding the value.

I would do an OPEN(case,"LOCK") and UPDATE (case,"UNLOCK") for good measure.

example something like

Code: Select all

#select cases you wish to update
SQL("mysql01","")
#for each case, update with a value
SQLFIRST
vcase = return-value
while vcase <> "?" DO
   OPEN (vcase, "LOCK")
   PUTDATA(vcase, {TPREF.Text},"ABC123")
   UPDATE(vcase, "")
   UPDATE(vcase, "UNLOCK")
   SQLNEXT
   vcase = return-value
END
I can't see it in any manual. It's used for 'caseless' autoroutines

revellbikes
Posts: 428
Joined: Fri Jun 15, 2012 12:44 pm
Has thanked: 11 times
Been thanked: 43 times

Re: PUTDATA

Post by revellbikes » Mon May 15, 2017 11:30 am

Thanks,

I've located a good working example on the RTA LOW VALUE NOTIFICATION AUTO maths item.

I can see some value in GETDATA, allowing an auto routine to retrieve case data without having to OPEN / LOCK / UNLOCK.

I'm surmising that PUTDATA should be able to put data into a specific case without the OPEN / LOCK / UNLOCK procedure, however it's not recommended perhaps?

steve
Posts: 384
Joined: Wed Nov 30, 2011 10:20 pm
Been thanked: 77 times

Re: PUTDATA

Post by steve » Mon May 15, 2017 12:35 pm

Given that all we have to go on with this command is the code published by Eclipse in the portal code, it would be wise just to emulate their locking requirements - namely ensure an OPEN LOCK, UPDATE "" , UPDATE UNLOCK wrapper around your PUTDATA. We can therefore assume PUTDATA does no case record level locking of its own and only exists to simplify 'caseless' autoroutines.

We can speculate what would happen if you used PUTDATA (and indeed plain old PUT to a linked case field) without locking. You risk your data being overwritten by a legitimate user/ process that has used LOCK. You also risk a user viewing and acting on stale data, depending on the timing of your PUT. You probably risk some other unforseen problems with a user performing UNDO or CANCEL in MCH, and no doubt more.

With GETDATA, the risk of not locking the file before you read data appears only to be one of how 'fresh' the data needs to be, and whether or not you are going to use that data to make changes to the same casefile.

If you get data from the DB whilst another user has the case open, you risk that the user has updated the value of the field you are GETTING, but has not yet saved the change. If you subsequently act on the data you retrieved in GETDATA (e.g. set diaries based on Case Status) then it would be wise to attempt to lock the file while doing the GETDATA so that you maintain integrity.

If you are just using GETDATA to e.g. count up a number of files at a certain case status at a given point in time, you might think locking the file whilst you GET is a little overkill, and just accept that a small number of files were open at the time with unsaved changes, so the count is slightly off.

But again, all we have to go on is the Eclipse supplied code, which in the Maths I have seen, also has the GETDATA inside an OPEN LOCK UPDATE UNLOCK wrapper. They presumably want data consistency for the whole transaction , especially since a number of processes (autoroutines and user linked actions) may act on the data at any one time with a greater chance of concurrent access.

I should add the usual disclaimer about the dangers of using undocumented features!

steve
Posts: 384
Joined: Wed Nov 30, 2011 10:20 pm
Been thanked: 77 times

Re: PUTDATA

Post by steve » Mon May 15, 2017 12:36 pm

for reference, from a chat with Eclipse about a year ago:

"[Eclipse dev] wanted to be able to trigger code from outside of cases (1 web call per check versus 1 on every case to see if there was an update etc) as this is hugely more efficient. At the time Auto Routines required an SQL to find cases to run code against and this was changed so they could be run without an SQL i.e. off case. However, as you were no longer running code on a case we needed some new maths commands (the ones above and when you are looking through my code you will also see GETDATA) so that we could use the normal functions but we had to specify which case to run them on.

Put simply (no pun intended) these commands are only ever used by us where we are running code off cases e.g. via an autoroutine with no SQL.
"

Post Reply