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

SHOVE()

This function inserts records into any stack belonging to any IMOD. Inserted records can be placed at any position within the stack.

Restriction

SHOVE() can specify a stack external to an IMOD only when the target stack has been declared public for writing.

Syntax

SHOVE([record],[recnum],[stack],[owner],,[postoption])

Parameters

record

Record to be inserted into the stack.

Default: A zero-length record is added.

recnum

Record number that is assigned to the inserted record. The existing records of recnum or higher increase their record numbers by one. The lowest record number is 1. Record 1 is the first record fetched by PULL. If the record number exceeds the total records currently on the stack, a QUEUE is performed.

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.

postoption

Wait option, which determines whether the owning IMOD waits for a record to appear on an external stack. Specify one of these values:

POST

Any outstanding wait is satisfied; the default.

NOPOST

An outstanding wait is not satisfied.

ONLYPOST

Any outstanding wait is satisfied, but a record is not placed on the stack.

Note: If you are placing several records onto an external stack, we recommend that you specify NOPOST for all but the final record. IMODs are time-sliced, and if the POST operation is performed before the final record is shoved on the stack, the IMOD task owning the stack could be dispatched to process before the final SHOVE is completed.

Return Codes

101 - 106

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

x = shove(rec,5)               /* A record is inserted into the
                                  current stack */
x = shove(rec,5,2)             /* A record is inserted into local
                                  stack 2 */
x = shove(rec,5,,453,,'post')  /* A record is inserted into IMOD
                                  453's default stack. Any
                                  outstanding wait is marked
                                  complete. */