| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions > ====== INSTANCE (return variable's thread instance address) ====== | [[inrange  check number within range .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[instring  return substring position .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**INSTANCE(**//variable//,threadno**)**

**Returns an unsigned integer value that references the address of the variable instance.**

{{blk2blue.jpg|blk2blue.jpg}}

| **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:

<code>
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
</code>   

**See Also:** [[thread  return current execution thread .htm|THREAD]] [[address_return_memory_address_.htm|ADDRESS]]