User Tools

Site Tools


instance_return_variable_s_thread_instance_address_1.htm
Navigation:  Language Reference > 13 - Built-in Functions > ====== INSTANCE (return variable's thread instance address) ====== Previous pageReturn to chapter overviewNext page

INSTANCE(variable,threadno)

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

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:

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

See Also: THREAD ADDRESS

instance_return_variable_s_thread_instance_address_1.htm.txt · Last modified: 2021/04/15 15:46 (external edit)