PULL()

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

PULL()

Use the PULL() function to remove records from any stack belonging to any IMOD. PULL() is a destructive operation.

Syntax

The PULL() function has this syntax:

record = PULL([stack],[owner],[cntl])

Arguments

The PULL() function takes these arguments:

record	Returned data or error text.
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.

Usage Notes

Whereas PULL translates all records to uppercase, PULL() does not. The function of PULL() is equivalent to PARSE PULL.
The results of a PULL() instruction may not be directly executed as a command. The result must first be assigned to a variable and then issued as a command. This is due to the REXX restriction that prohibits a command string (not in quotes) from beginning with a reserved keyword, in this case, PULL.
PULL() can specify a stack external to the current IMOD only when the target stack has been declared public for both reading and writing by the owning IMOD task using the PUBSTACK() function.

Return Codes

The PULL() function produces these return codes:

101 - 103 ARG n INVALID

122 RECORD NOT FOUND

125 SPECIFIED IMOD NOT FOUND

126 STACK NOT SPECIFIED AND NO DEFAULT

127 REQUESTED STACK DOES NOT EXIST

128 SPECIFIED IMOD/STACK NOT AUTHORIZED

Example

rec = pull()                /* A record is retrieved from the
                               current stack */
rec = pull(2)               /* A record is retrieved from local
                               stack 2 */
rec = pull(,453,'owner')    /* A record is retrieved from IMOD 
                               453's default stack. The control
                               information will be placed in the
                               variable named "owner" */

Tell Technical Publications how we can improve this information