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" */