| Navigation: Language Reference > 13 - Built-in Functions > ====== INSTANCE (return variable's thread instance address) ====== |    |
INSTANCE(variable,threadno)
Returns an unsigned integer value that references the address of the variable instance.
| INSTANCE | Returns the address of a variable or entity's thread instance. |
| variable | Label of a variable, field, FILE, KEY or QUEUE or reference variable. |
| threadno | A numeric constant, variable, or expression that can be evaluated as a SIGNED integer. |
The INSTANCE procedure evaluates the condition of the variable parameter and its thread number referenced by the threadno parameter and returns the following results:
If the value of threadno is not zero(0), and the thread referenced by threadno is not started (or an instance of variable is not allocated for the thread referenced by threadno), INSTANCE returns zero(0). Otherwise, INSTANCE returns the address of the variable instance allocated for the active thread referenced by threadno.
The variable parameter must be either an instance of a threaded variable or entity allocated for the current thread, or a reference variable pointing to a memory location whose address has been obtained by the call to INSTANCE(variable, 0). Otherwise, the INSTANCE function returns an address of the passed variable.
If the threadno parameter is set to zero(0), INSTANCE returns the address of the variable that is assigned by the program loader. This is also known as the variables thread independent ID.
INSTANCE can be used instead of the ADDRESS( ) statement when ADDRESS( ) is not valid or available (e.g. FILE and QUEUE structures). ADDRESS(QUEUE) is a legal call, but it returns the address of the queue's internal buffer. On the other hand, INSTANCE(QUEUE,THREAD()) returns the address of the queue's internal structure.
For example, given the following QUEUE declarations:
SomeQueue QUEUE
...
END
QueueRef &QUEUE
The following assignment is correct:
QueueRef &= INSTANCE (SomeQueue, Somethread)
while the assignment shown below is not correct:
QueueRef &= ADDRESS (SomeQueue)
and sets the QueueRef variable to the wrong value.
INSTANCE** is also valuable when you need the thread independent ID of the variable.
| **Return Data Type:** | LONG |
Example:
addressvar = INSTANCE(SalesFile,THREAD())
!return address of SalesFile entity on active thread
addressvar = INSTANCE(GLO:LoginID, 0)
!get the thread independent ID of a global threaded variable
Expanded Example:
PROGRAM
MAP
PROC1()
END
ThreadClass CLASS,TYPE
A STRING(10)
END
NoThreadClass CLASS,TYPE
TC &ThreadClass
Init PROCEDURE(ThreadClass TC)
GetA PROCEDURE(),STRING
SetA PROCEDURE(STRING A)
END
MyClass NoThreadClass
MyThreadClass ThreadClass,THREAD
!If MyThreadClass was not threaded, the value of "A" will be the same for each
!thread, and access to it should be synchronized
AppFrame APPLICATION('Application'),AT(,,505,318),|
FONT('MS Sans Serif',8,,FONT:regular),|
CENTER,ICON('WAFRAME.ICO'),STATUS(-1,80,120,45),SYSTEM,MAX,RESIZE
END
CODE
MyClass.Init(MyThreadClass)
OPEN(AppFrame)
START(PROC1)
START(PROC1)
ACCEPT
END
PROC1 PROCEDURE()
LOC:SETVAL STRING(10)
LOC:GETVAL STRING(10)
Window WINDOW('Win'),AT(,,119,100),|
FONT('MS Sans Serif',8,,FONT:regular),IMM,GRAY,AUTO,MDI
BUTTON('Set Value'),AT(5,6,41,14),USE(?SET)
ENTRY(@s10),AT(53,7,60,10),USE(LOC:SETVAL)
BUTTON('Get Value'),AT(5,25,41,14),USE(?GET)
ENTRY(@s10),AT(53,28,60,10),USE(LOC:GETVAL)
BUTTON('&Close'),AT(35,50,46,14),USE(?Close),LEFT,STD(STD:Close)
PROMPT('Each window is getting/setting the value of its own? &|
' instance of the ThreadClass'),AT(5,67,107,31),USE(?Description)
END
CODE
OPEN(Window)
0{PROP:TEXT}=0{PROP:TEXT}&'-'&THREAD()
LOC:SETVAL = THREAD()
MyClass.SETA(LOC:SETVAL)
ACCEPT
CASE EVENT()
OF EVENT:ACCEPTED
CASE ACCEPTED()
OF ?GET
LOC:GETVAL=MyClass.GETA()
DISPLAY()
OF ?SET
MyClass.SETA(LOC:SETVAL)
END
END
END
NoThreadClass.Init PROCEDURE(ThreadClass TC)
CODE
!Storing the "Thread independent ID" for the class
SELF.TC &= INSTANCE(TC,0)
NoThreadClass.GetA PROCEDURE()
LTC &ThreadClass
CODE
! SELF.TC contain the "Thread independent ID" for the threaded class
LTC &= INSTANCE(SELF.TC,THREAD())
! LTC is a reference to the instance for the current thread
RETURN LTC.A
NoThreadClass.SetA PROCEDURE(STRING A)
LTC &ThreadClass
CODE
! SELF.TC contains the "Thread independent ID" for the threaded class
LTC &= INSTANCE(SELF.TC,THREAD())
! LTC is a reference to the instance for the current thread
LTC.A = A