POP Method (DATASET)

The Pop method retrieves data items from the DATASET stack. By default, this method retrieves the last data item Push on the DATASET stack in a LIFO (Last In First Out) mode. This default behavior can be changed to use a FIFO (First In First Out) mode by using the {flags} parameter. Once the Pop method executes the data item is automatically deleted from the DATASET. This method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A DATASET object.

return

Optional. A Character String Variable that returns the data string for the data item. Otherwise, an error string formatted as "$ERROR$=errorinfo" is returned.

flags

Optional. A Numeric Variable, decimal number, or Numeric expression that defines a bit mask value that is used to control Pop method behaviors.

Flags Affected: EOS, OVER, ZERO

Notes:

1. The EOS flag is set if the returned data is truncated because the {return} variable is too small.

2. The ZERO and OVER flags are always cleared.

3. The {flags} bit mask values found in plbmeth.inc are definedfor future usage as follows:

 

Equate	Value	Description
$DSF_POP_FIFO	0x00000001	Use FIFO mode for Pop method.
$DSF_POP_GET_KEY_AND_DATA	0x00000002	Return both the key string followed by a comma which is followed with all of the data being returned.

 

4. When this method generates an error, the {return} variable contains the error string formatted as follows:

 

$ERROR$=nnn

                

Where the 'nnn' error value as follows:

 

Error Code	Description
1	The DATASET is empty.
10	The item data size is too large for DATASET output buffer! Sunbelt internal error.

 

See Also: Method Syntax,