PUSH & POP ILF Statements

PUSH Statement

The PUSH statement saves a field or record value on an internally maintained stack for the indicated field or record. The structure of the statement is:

***** PUSH     *** ********************** *** ***************
(1)            (2) (3)                    (4) (5)

(1) T/F execution conditions 
(2) Application ID
(3) File Name, field name, or predefined field
(4) Occurrence (constant/index)
(5) Data item type (FIELD, RECORD, DEFAULT FIELD, DEFAULT RECORD, ORIGINAL FIELD, ORIGINAL RECORD)

A distinct stack is associated with each field name and with each file name.

The stack has the internal structure of a LIFO list, i.e. the last value pushed onto the stack for a field is the first value popped from the stack.

The contents of predefined fields can also be saved using the PUSH statement. However, it is invalid to use the PUSH statement for predefined fields that are non-modifiable, since the POP command is invalid for those fields.

The scope of a stack is the same as the scope of the associated field or file. 

The Data item type specification identifies which field value or record is to be pushed onto the stack.  If FIELD or RECORD is specified, then the  current value of the field or record is pushed onto the stack.  If DEFAULT FIELD or DEFAULT RECORD is specified, then the  default value of the field or record is pushed onto the stack.  If ORIGINAL FIELD or ORIGINAL RECORD is specified, then the original value of the field or record is pushed onto the stack.  ORIGINAL FIELD and ORIGINAL RECORD may only be specified if the process being executed has a PCF.

Since there is only one stack for each field name and one stack for each file name, FIELD, DEFAULT FIELD, and ORIGINAL FIELD all push the indicated values onto a common (shared) stack for the specified field name and RECORD, DEFAULT RECORD, and ORIGINAL RECORD all push the indicated record buffers onto a common (shared) stack for the specified record (file) name.

Multiple occurrences of a field also share a common stack.

A sub-string field and a synonym field will each have their own stack since they have field names that are distinct from the field that they are derived from.

POP Statement 

The POP statement pops a field or record value from an internally maintained stack and sets it into the indicated field or record. The structure of the statement is:

***** POP      *** ********************** *** ***************
(1)            (2) (3)                    (4) (5)

(1) T/F execution conditions 
(2) Application ID
(3) File Name, field name, or predefined field
(4) Occurrence (constant/index)
(5) Data item type (FIELD, RECORD, DEFAULT FIELD, DEFAULT RECORD, ORIGINAL FIELD, ORIGINAL RECORD)

      POP      AAA FILE OR FIELD NAME   OCC      TYPE

The new PUSH and POP statements allow designers to load (PUSH) field or record data onto an internally maintained stack, and then retrieve (POP) them for use later. The structure of the statement is: (AAA is the application ID, OCC is the [optional] occurrence number.)

The TYPE field is used to specify either FIELD or RECORD, and load/retrieve accordingly. Scanning on the TYPE field displays six possible values (FIELD, DEFAULT FIELD, ORIGINAL FIELD, RECORD, DEFAULT RECORD, ORIGINAL RECORD), apparently because the structure of the statement was taken from the STORE/RESTORE statements. However, it is important to note that there is only one stack for each FIELD, and one for each RECORD; therefore specifying DEFAULT FIELD or ORIGINAL FIELD is no different than specifying FIELD. Note, though, that an error will occur if you specify ORIGINAL FIELD on something other than the Process Control File.

The POP statement retrieves values in the reverse order that they were PUSHED, i.e. a LIFO function, and returns a TRUE flag if a value was successfully POPped, and a FALSE flag if the stack was empty. There is no automatic way to empty a stack, other than to repeat the POP statement in a loop until it returns a FALSE.

A sub-string field and a synonym field will each have their own stack since they have distinct field names. A field with multiple occurrences will have one stack. For example, a field named MYFILE FLD is defined with 2 occurrences. If you pushed MYFILE FLD (001) then pushed MYFILE FLD (002) the data will be saved in the stack named MYFILE FLD. To retrieve the saved values you would POP MYFILE FLD twice. The first POP would return MYFILE FLD (002), the second POP would return MYFILE FLD (001) as described above.

The stack inherites the scope (subprocess, related, or detached) from the field that is PUSH'ed.

An ideal use for PUSH and POP is to load virtual keystrokes (user options) into a stack, and have them executed automatically and sequentially. See the section on SELECT below for an example of this usage.

Examples

The following example shows how PUSH and POP can be used to swap the values of occurrences 1 and 2 of a field.

      PUSH     TOE ORDER1 SALESPERSON     001 FIELD
      PUSH     TOE ORDER1 SALESPERSON     002 FIELD
      POP      TOE ORDER1 SALESPERSON     001 FIELD
      POP      TOE ORDER1 SALESPERSON     002 FIELD

One use for PUSH and POP is to load virtual keystrokes (user options) into a stack, and have them executed automatically and sequentially. See the section on SELECT below for an example of this usage.

Comments:

Here are a couple of ideas for additional related statements:

• POP ALL - Empty the stack for the specified field or record
• POP FIFO - POP the specified field or record from the bottom of the stack - FIFO (first in, first out) manner, rather than LIFO

-- SteveFrizzell - 01 Oct 2008

-- AlKalter - 04 Apr 2008