CA-GSS Statements and Commands › GSS Extended Functions › IO Functions › Number, String, and Variable Functions › System Information Functions › TUG()

TUG()

Use the TUG() function to obtain a copy of any record on any stack belonging to any IMOD task. A TUG() operation provides you with a copy of a record. Following a TUG(), the record remains on the stack.

Syntax

The TUG() function has this syntax:

record = TUG([recnum],[stack],[owner],[cntl])

Arguments

The TUG() function takes these arguments:

record

Returned record or error text.

recnum

Record number to be copied from the stack.

stack

Number of the stack to be referenced.

Default: If a local stack is referenced, the current stack (as set by the SWAPSTAK() function); otherwise, the value is set by the owning IMOD task using the PUBSTACK(DEFAULT) function.

owner

IMOD ID of the stack's owner (for external reference). This value can be obtained from the variable imod_id in the owning IMOD task. It is also the value returned by the SPAWN() function.

Default: Current IMOD task.

cntl

Name of a variable to receive the control information stored with the record.

Default: Control information is not retrieved.

Return Codes

The TUG() function produces these return codes:

101 - 105

ARG n INVALID

122

STACK NOT SPECIFIED AND NO DEFAULT

123

SPECIFIED STACK DOES NOT EXIST

125

SPECIFIED IMOD NOT FOUND

126

STACK WRITE FAILED

127

REQUESTED STACK DOES NOT EXIST

128

SPECIFIED IMOD/STACK NOT AUTHORIZED

Example

rec = tug(2)              /* Record number 2 is copied from the
                             current stack */
rec = tug(2,5)            /* Record number 2 is copied from local
                             stack 5 */
rec = tug(2,,453,'data')  /* Record 2 is copied from IMOD 453's
                             default stack and control information
                             is placed in the variable data. */

Usage Note

TUG() can specify a stack external to an IMOD task only when the target stack has been declared public for reading by the owning task.