INSTANCE (return variable's thread instance address)

Top  Previous  Next

 

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

 

See Also: THREAD