Data Stack Routine - IBM-REXX

The data stack routine is called to handle any requests for data stack services. The routine is called when an exec wants to perform a data stack operation or when a program needs to process data stack-related operations. The routine is called for the following:

  • PUSH
  • PULL
  • QUEUE
  • QUEUED()
  • MAKEBUF
  • DROPBUF
  • NEWSTACK
  • DELSTACK
  • QSTACK
  • QBUF
  • QELEM
  • MARKTERM
  • DROPTERM

The name of the system-supplied data stack routine is IRXSTK. If you provide your own data stack routine, your routine can handle all of the data stack requests or your routine can perform pre-processing and then call the system routine, IRXSTK. If your routine handles the data stack requests without calling the system-supplied routine, your routine must manipulate its own data stack.

If your data stack routine performs pre-processing and then calls the system routine IRXSTK, your routine must pass the address of the environment block for the language processor environment to IRXSTK.An application running in any address space can invoke IRXSTK to operate on the data stack. The only requirement is that a language processor environment has been initialized.

Parameter 1 indicates the type of function to be performed against the data stack. If the data stack routine is called to pull an element off the data stack (PULL function) and the data stack is empty, a return code of 4 indicates an empty data stack. However, you can use the PULLEXTR function to bypass the data stack and read from the input stream (for example, from the terminal in TSO/E foreground).

If the data stack routine is called and a data stack is not available, all services operate as if the data stack were empty. A PUSH or QUEUE will seem to work, but the pushed or queued data is lost. QSTACK returns a 0. NEWSTACK will seem to work, but a new data stack will not be created and any subsequent data stack functions will operate as if the data stack is permanently empty.

The maximum string that can be placed on the data stack is one byte less than 16 MB. REXX does not check the content of the string, so the string can contain any hexadecimal characters.

If multiple data stacks are associated with a single language processor environment, all data stack operations are performed on the last data stack that was created under the environment. If a language processor environment is initialized with the NOSTKFL flag off, a data stack is always available to execs that run in that environment. The language processor environment might not have its own data stack. The environment might share the data stack with its parent environment depending on the setting of the NEWSTKFL flag when the environment is initialized.

If the NEWSTKFL flag is on, a new data stack is initialized for the new environment. If the NEWSTKFL flag is off and a previous environment on the chain of environments was initialized with a data stack, the new environment shares the data stack with the previous environment on the chain.The name of the data stack replaceable routine is specified in the STACKRT field in the module name table.

Entry Specifications

For the data stack replaceable routine, the contents of the registers on entry are described below. The address of the environment block can be specified in either register 0 or in the environment block address parameter in the parameter list.

Register 0 Address of the current environment block

Register 1 Address of the parameter list

Registers 2-12 Unpredictable

Register 13 Address of a register save area

Register 14 Return address

Register 15 Entry point address

Parameters

Register 1 contains the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter. The high-order bit of the last address in the parameter list must be set to 1 to indicate the end of the parameter list. The describes the parameters for the data stackroutine.

Parameters for the Data Stack Routine

Parameters for the Data Stack Routine

Functions Supported for the Data Stack Routine

The function to be performed by the data stack routine is passed in parameter 1. The valid functions are described below. The functions operate on the currently active data stack

PUSH
Adds an element to the top of the data stack.

PULL
Retrieves an element off the top of the data stack.

PULLEXTR
Bypasses the data stack and reads a string from the input stream. In TSO/E foreground, PULLEXTR reads from the terminal. In TSO/E background, PULLEXTR reads from SYSTSIN. In non-TSO/E address spaces, the PULLEXTR function reads from the input stream as defined by the INDD field in the module name table. The default is SYSTSIN.

PULLEXTR is useful if the data stack is empty or you want to bypass the data stack entirely. For example, suppose you use the PULL function and the data stack routine returns with a return code of 4, which indicates that the data stack is empty. You can then use the PULLEXTR function to read a string from the input stream.

QUEUE
Adds an element at the logical bottom of the data stack. If there is a buffer on the data stack, the element is placed immediately above the buffer.

QUEUED
Returns the number of elements on the data stack, not including buffers.

MAKEBUF
Places a buffer on the top of the data stack. The return code from the data stack routine is the number of the new buffer. The data stack initially contains one buffer (buffer 0), but MAKEBUF can be used to create additional buffers on the data stack. The first time MAKEBUF is issued for a data stack, the value 1 is returned.

DROPBUF n
Removes all elements from the data stack starting from the “n”th buffer. All elements that are removed are lost. If n is not specified, the last buffer that was created and all subsequent elements that were added are deleted.

For example, if MAKEBUF was issued six times (that is, the last return code from the MAKEBUF function was 6), and the command

DROPBUF 2

is issued, five buffers are deleted. These are buffers 2, 3, 4, 5, and 6.DROPBUF 0 removes everything from the currently active data stack.

NEWSTACK
Creates a new data stack. The previously active data stack can no longer be accessed until a DELSTACK is issued.

DELSTACK
Deletes the currently active data stack. All elements on the data stack are lost. If the active data stack is the primary data stack (that is, only one data stack exists and a NEWSTACK was not issued), all elements on the data stack are deleted, but the data stack is still operational.

QSTACK
Returns the number of data stacks that are available to the running REXX exec.

QBUF
Returns the number of buffers on the active data stack. If the data stack contains no buffers, a 0 is returned.

QELEM
Returns the number of elements from the top of the data stack to the next buffer. If QBUF = 0, then QELEM = 0. MARKTERM Marks the top of the active data stack with the equivalent of a TSO/E terminal element, which is an element for the TSO/E input stack. The data stack now functions as if it were just initialized. The previous data stack elements cannot be accessed until a DROPTERM is issued.

If you issue a MARKTERM, you must issue a corresponding DROPTERM to delete the terminal element that MARKTERM created.MARKTERM is available only to calling programs to put a terminal element on the data stack. It is not available to REXX execs.

DROPTERM
Removes all data stack elements that were added after a MARKTERM was issued, including the terminal element created by MARKTERM. The data stack status is restored to the same status prior to the MARKTERM.DROPTERM is available only to calling programs to remove a terminal element from the data stack. It is not available to REXX execs.

Return Specifications

For the data stack routine, the contents of the registers on return are:

Registers 0-14 Same as on entry

Register 15 Return code

Return Codes

The shows the return codes for the data stack routine. These are the return codes from the routine itself. They are not the return codes from any ofthe TSO/E REXX commands, such as NEWSTACK, DELSTACK, and QBUF that are issued. The command’s return code is placed into the REXX special variable RC, which the exec can retrieve.The data stack routine returns the return code in register 15. If you specify the return code parameter (parameter 6), the routine also returns the return code in the parameter.

Return Codes for the Data Stack Replaceable Routine

Return Codes for the Data Stack Replaceable Routine

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-REXX Topics