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

PULL()

This function removes records from any stack belonging to any IMOD. PULL() is a destructive operation.

Syntax

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

Parameters

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 owning IMOD task sets the value using the PUBSTACK(DEFAULT) function.

owner

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

Default: Current IMOD task.

cntl

Name of a variable to receive the control information that is 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 cannot 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 reading and writing by the owning IMOD task using the PUBSTACK() function.

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