PUSH & POP ILF Statements

Release 5.0.0 of APPX implements the PUSH and 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 PUSH statement is used to add field and record values to a stack.

The POP statement is used to retrieve field and record values from a stack.

The stack has the internal structure of a LIFO list, i.e. the last value pushed onto the stack for a field or record is the first value popped from the stack. There is no predefined limit as to how many field or record values may be pushed onto a stack.

The value of the source field or record is not changed when a PUSH statement is executed.

You may execute a PUSH statement for a specific field or file more than once before you execute a POP statement to retrieve a value from the stack. Each time that you execute a PUSH statement, the value of the referenced field or record is "pushed" onto the top of the stack associated with that field or file. Each time that you execute a POP statement, the next value is retrieved from the stack of the referenced field or record, stored as the current value of the referenced field or record, and removed from the top of 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. For example, if the scope of the referenced field is RELATED, then the scope of the associated stack will also be RELATED.

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 referenced field is a field in the PCF or if the referenced file is the PCF of the currently executing process.

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 value onto a common (shared) stack for the specified field name and RECORD, DEFAULT RECORD, and ORIGINAL RECORD all push the indicated record buffer 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 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 as the current value of 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)

The POP statement is used to pop (retrieve) a value that was saved with a PUSH statement.

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 or record is the first value popped from the stack. There is no predefined limit as to how many field or record values may be pushed onto a stack.

You may execute a POP statement for a specific field or file more than once. Each time that you execute a POP statement, the value from the "top" of the stack of the referenced field or record is saved as the current value of the referenced field or record and the value is removed from the stack. The POP statement also sets the True/False indicator. If the stack for the referenced field or file contains a value, then the stack is popped and the next level of the true/false status indicator is set to T (true). If the stack is empty, then the referenced field is set to its default value and the next level of the true/false indicator is set to F (false).

Predefined fields may be referenced by a PUSH or POP statement. However, it is invalid to use the PUSH or POP statement for predefined fields that are non-modifiable.

The scope of a stack is the same as the scope of the associated field or file. For example, if the scope of the referenced field is RELATED, then the scope of the associated stack will also be RELATED.

When a POP statement references a field with an occurrence, the next value from the stack is popped into the specified occurrence of the reference field.

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.

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 for an example of this usage.

Issues:

1. The Data Item Type specification of the POP statement should only allow two options, FIELD and RECORD. The current implementation of the statement also allows DEFAULT FIELD and ORIGINAL FIELD to be specified. Both are treated the same as if FIELD was specified. DEFAULT RECORD and ORIGINAL RECORD are also allowed and are treated as if RECORD was specified. Application designers should always specifiy either FIELD or RECORD on a POP statement. Do not specify DEFAULT FIELD, ORIGINAL FIELD, DEFAULT RECORD, or ORIGINAL RECORD on the POP statement. These options may not be supported in a future release.

Comments:

Read what other users have said about this page or add your own 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

Note that while PUSH/POP are similar to STORE/RESTORE, there are some significant differences. The obvious one is that multiple sequential values can be PUSHed and POPped, while STORE allows only one. There is also a difference in how Group Header fields are handled. With STORE/RESTORE, you can STORE a group header and then RESTORE individual values from within it. But because PUSH/POP recognizes different field names, that approach will not work the same way.

Example: Assume ORDER2 KEY is the key to the ORDER2 file, and is made up of ORDER2 ORDER NO and ORDER2 LINE NO. If you STORE ORDER2 KEY, then doing a RESTORE ORDER2 LINE NO will retrieve that portion of the key that was stored. But if you PUSH ORDER2 KEY and try to POP ORDER2 LINE NO, you'll see that the individual value was not retrieved.

-- AlKalter - 2012-02-16

-- AlKalter - 04 Apr 2008