StackQuery / DMSSTKQ - Query the Program Stack

Read syntax diagramSkip visual syntax diagramStackQueryDMSSTKQ,1 retcode , reascode , buffer_number , lines , top_buffer_number
Notes:
  • 1 The comma is omitted after the routine name when the routine is called directly.

Call Format

The format for invoking a CSL routine is language dependent. This routine can be called directly by either name or indirectly through DMSCSL as DMSSTKQ. The routine name is the first parameter in DMSCSL’s parameter list:

DMSSTKQ
(input, CHAR, 8) can be passed as a literal or in a variable.

For more information and examples of the call formats, see Calling VMLIB CSL Routines.

Purpose

Use the StackQuery routine to query the number of lines in the program stack or the number of lines in a specific stack buffer. The number of the top buffer in the program stack is also returned.

Parameters

retcode
(output, INT, 4) is a variable for the return code from StackQuery.
reascode
(output, INT, 4) is a variable for the reason code from StackQuery.
buffer_number
(input, INT, 4) is a value that indicates what data should be returned in the lines parameter. The buffer number parameter can be set to:
Value
Effect
0–n
The number of a particular buffer, 0 through the number of the top buffer in the program stack. StackQuery returns the number of lines in that buffer.
vm_stk_query_all_buffers
StackQuery returns the number of lines in the program stack.
vm_stk_query_top_buffer
StackQuery returns the number of lines in the top buffer of the program stack.
lines
(output, INT, 4) is a variable to hold the number of lines, as specified by buffer_number.
top_buffer_number
(output, INT, 4) is a variable to hold the number of the top buffer in the program stack.

Usage Notes

  1. The top buffer number is always returned, even when the return code indicates an error.
  2. StackQuery returns information about the program stack. It can replace calls to DMSERP to extract information (NUM_TERM_INPUT_LINES and NUM_FINISHED_READS) that is necessary to calculate the number of lines in the program stack.

Return Codes and Reason Codes

Severity Reason Code Description
ERROR 99558 There is no buffer with the specified buffer number.
ERROR 99551 Invalid buffer number.

For lists of the possible return codes from StackQuery, see Return Codes.

The following table lists the reason codes returned by StackQuery. ERROR means the request failed. The return code from successful requests is vm_success. Errors cause return code vm_error.

Severity Reason Code Description
ERROR vm_stk_no_buffer There is no buffer with the specified buffer number.
ERROR vm_stk_bad_buffer_number Invalid buffer number.

Programming Language Binding Files

Table 1. Binding Files for Function Definitions and Constants
Language Binding File
Assembler VMASMSTK MACRO
C VMCSTK H
COBOL VMCOBSTK COPY
FORTRAN VMFORSTK COPY
PASCAL VMPASSTK COPY
PL/I VMPLISTK COPY
REXX VMREXSTK COPY
Table 2. Binding Files for Return Codes and Reason Codes
Language Binding File
Assembler VMASMRET MACRO
C VMCRET H
COBOL VMCOBRET COPY
FORTRAN VMFORRET COPY
PASCAL VMPASRET COPY
PL/I VMPLIRET COPY
REXX VMREXRET COPY