Retrieve Call Stack (QWVRCSTK) API


  Required Parameter Group:


  Default Public Authority: *USE

  Threadsafe: Yes

The Retrieve Call Stack (QWVRCSTK) API returns the call stack information for the specified thread. The first call stack entry returned corresponds to the most recent call in the thread.


Authorities and Locks

Job Authority
The API must be called within the thread for which the call stack is being retrieved, or the caller of the API must be running under a user profile that is the same as the job user identity of the job containing the thread for which the call stack is being retrieved. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority or GUI thread control authority.

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.

The caller of the API must have service (*SERVICE) special authority to retrieve advanced details for format CSTK0300.


Required Parameter Group

Receiver variable
OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. For example, this may mean that the value in the number of call stack entries returned field doesn't match the value in the number of call stack entries for thread field.

Length of receiver variable
INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

Format of receiver information
INPUT; CHAR(8)

The format of the information returned in the receiver variable. The possible format name is:


Job identification information
INPUT; CHAR(*)

The information that is used to identify the thread within a job for which call stack information is to be returned. See Format of Job Identification Information for details.

Format of job identification information
INPUT; CHAR(8)

The format of the job identification information. The possible format names are:

Note: If the thread handle is available, Format JIDF0200 provides a faster method of accessing a thread that is not the current thread than Format JIDF0100.

Error code
I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.


Format CSTK0100

This format will contain OPM and ILE stack frames. For details about the fields listed, see Field Descriptions.



Format CSTK0200

This format will contain OPM, ILE, IBM PASE for i, and Java program stack frames. For details about the fields listed, see Field Descriptions.



Format CSTK0300

This format will contain OPM, ILE, IBM PASE for i, Java, Licensed Internal Code, and IBM PASE for i Kernel stack frames. To use this format, the caller of the API must be running under a user profile that has service (*SERVICE) special authority. For details about the fields listed, see Field Descriptions.



Format of Call Stack Entry Data

The format of the information returned for a given stack frame.

STKE0100 Format

This format describes the data that is returned for an OPM or ILE program stack frame. For details about the fields listed, see Field Descriptions.



STKE0200 Format

This format describes the data that is returned for IBM PASE for i and IBM PASE for i Kernel stack frames. For details about the fields listed, see Field Descriptions.



STKE0300 Format

This format describes the data that is returned for Licensed Internal Code stack frames. For details about the fields listed, see Field Descriptions.



STKE0400 Format

This format describes the data that is returned for Java stack frames. For details about the fields listed, see Field Descriptions.



Field Descriptions

32-bit indicator. Whether the invocation is running 32-bit or 64-bit IBM PASE for i code. The possible values are:

Activation group name. The name of the activation group within which the program or procedure is running. Possible special values are:

Activation group number. The number of the activation group within which the program or procedure is running. This is an internal number that uniquely identifies the activation group within the job. It is recomended that the activation group number long be used to uniquely identify the activation group. The value returned in this field may become invalid due to the presision of the storage.

Activation group number long. The number of the activation group within which the program or procedure is running. This is an internal number that uniquely identifies the activation group within the job.

Alternate resume point indicator. Whether the current entry is a second entry for a given invocation. This flag is only used when the system can not reliably determine which of two possible resume points will be used when an invocation resumes execution. The possible values are:

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Call stack entry data. Specifies the returned data for a given stack frame.

Control boundary. Whether a control boundary is active for a particular program or procedure. Possible values are:

Displacement to call stack entry data. The displacement in bytes from the beginning of the call stack entry to the specific data for the call stack entry.

Displacement to Java class name. The displacement in bytes from the beginning of the call stack entry to the Java class name. This field is zero if no Java class name can be determined.

Displacement to Java file name/directory. The displacement in bytes from the beginning of the call stack entry to the Java file name/directory. This field is zero if no Java file name/directory can be determined.

Displacement to Java method name. The displacement in bytes from the beginning of the call stack entry to the Java method name. This field is if no Java method name can be determined.

Displacement to Java method signature. The displacement in bytes from the beginning of the call stack entry to the Java method signature. This field is if no Java method signature can be determined.

Displacement to Java source file name. The displacement in bytes from the beginning of the call stack entry to the Java source file name. This field is zero if no Java source file name can be determined.

Displacement to load module name. The displacement in bytes from the beginning of the call stack entry to the load module name. This field is zero if no load module name can be determined.

Displacement to load module path. The displacement in bytes from the beginning of the call stack entry to the load module path. This field is zero if no load module path can be determined.

Displacement to procedure name. The displacement in bytes from the beginning of the call stack entry to the procedure name. This field is zero if no procedure name can be determined.

Displacement to source path and file. The displacement in bytes from the beginning of the call stack entry to the source path and file. This field is zero if no source path and file can be determined.

Displacement to statement identifiers. The displacement in bytes from the beginning of the call stack entry to the array of statement identifiers. This field is zero if the number of statement identifiers is zero.

Format name of call stack entry data. The format of the call stack entry data returned for a given stack frame. The possible format names are:

Information status. Whether the call stack entry information could be successfully retrieved.

Instruction address. The IBM PASE for i memory address for the instruction that will run when execution resumes for the invocation.

Instruction offset. The offset in bytes from the beginning of the start of the procedure to the instruction that is either the suspend point for the invocation or the resume point for the invocation.

Java byte code offset. The offset in bytes from the beginning of the Java method byte codes to the resume point for the invocation. This field is zero if no Java byte code offset can be determined.

Java class name. The name of the Java class at this level of the call stack.

Java coded character set ID. The coded character set identifier used to return Java information including the Java class name, Java method name, Java method signature, Java file name/directory, and Java source file name.

Java file name/directory. The name of the Java file and directory that provides the location of where the Java class was loaded at this level of the call stack. If the Java class was loaded from a .jar or .zip file, then the location will be the path to and the name of the .jar or .zip file. If the class was loaded from a .class file, then the location will be the directory from which the class was loaded.

Java method name. The name of the Java method at this level of the call stack.

Java method signature. The signature of the Java method at this level of the call stack.

Java method type. The type of Java method. The Java method can only be one of the following types. The possible values are:

Java source file name. The name of the Java source file at this level of the call stack.

Kernel indicator. Whether the invocation is running IBM PASE for i kernel code. The possible values are:

Length of call stack entry data. The length of the stack entry data.

Length of Java class name. The length of the Java class name. This field is zero if no Java class name can be determined.

Length of Java file name/directory. The length of the Java file name/directory. This field is if no Java file name/directory can be determined.

Length of Java method name. The length of the Java method name. This field is zero if no Java method name can be determined.

Length of Java method signature. The length of the Java method signature. This field is zero if no Java method signature can be determined.

Length of Java source file name. The length of the Java source file name. This field is if no Java source file name can be determined.

Length of load module name. The length of the load module name. This field is zero if no load module name can be determined.

Length of load module path. The length of the load module path. This field is if no load module path can be determined.

Length of procedure name. The length of the procedure name. This field is zero if no procedure name can be determined.

Length of source path and file. The length of the source path and file. This field is zero if no source path and file can be determined.

Length of this call stack entry. The length of this call stack entry.

Line number. The line number where the invocation was interrupted. This value is zero if no line number can be determined.

Load module name. The name of the load module at this level of the call stack.

Load module path. The path to the load module at this level of the call stack.

MI instruction number. The current machine instruction number in the program. This field is not meaningful for integrated language environment (ILE) procedures. A zero is returned for ILE procedures.

Module library name. The name of the library in which the module is located. The following special values may be returned:

Module name. The module containing the integrated language environment (ILE) procedure. The following special values may be returned:

Number of call stack entries for thread. The number of call stack entries that are associated with this thread. A zero is returned if the call stack could not be retrieved.

Number of call stack entries returned. The number of call stack entries returned in the receiver variable.

Number of statement identifiers. The number of statement identifiers returned. This field is zero if the program or procedure was not created with debugging tables.

Offset to call stack entry information. The offset in bytes from the beginning of the receiver variable to the first call stack entry.

Procedure name. The name of the procedure at this level of the call stack.

Program ASP name. The name of the auxiliary storage pool (ASP) device in which the program is located. The following special values also may be returned:

Program ASP number. The numeric identifier of the ASP containing the program. The following values may be returned:

Program library ASP name. The name of the ASP in which the program library is located. The following special values also may be returned:

Program library ASP number. The numeric identifier of the ASP containing the program library. The following values may be returned:

Program library name. The name of the library in which the program is located. The following special values may be returned:

Program name. The name of the program at this level of the call stack. This can be any type of program object, including objects of type *PGM and *SRVPGM. The following special value may be returned:

Request level. The level of the request-processing program or procedure. A zero is returned if the program or procedure has not received a request message.

Reserved. An unused field.

Returned thread identifier. A value which uniquely identifies the thread within the job.

Source path and file. The path and name for the source file used to create the procedure.

Statement identifiers. The high-level language statement identifier. If this field contains the character representation of a number, the number is right-adjusted in the field and padded on the left with zeros (for example, '0000000246'). If the call stack entry is for an integrated language environment (ILE) procedure, more than one statement identifier may exist because of the compilers used for ILE languages.


Format of Job Identification Information

The format of the information needed to identify the thread for which call stack information will be returned.


JIDF0100 Format



Field Descriptions

Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.

Job name. A specific job name or one of the following special values:

Job number. A specific job number, or blanks when the job name specified is a special value.

Reserved. An unused field. This field must contain hexadecimal zeros.

Thread identifier. A value which uniquely identifies a thread within a job. If the thread indicator is not 0, this field must contain hex zeros.

Thread indicator. A value which is used to specify the thread within the job for which information is to be retrieved. The following values are supported:

User name. A specific user profile name, or blanks when the job name specified is a special value.


JIDF0200 Format



Field Descriptions

Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.

Job name. A specific job name or one of the following special values:

Job number. A specific job number, or blanks when the job name specified is a special value.

Reserved. An unused field. This field must contain hexadecimal zeros.

Thread handle. A value which addresses a particular thread within a job. While the thread identifier uniquely identifies the thread within the job, the thread handle can improve performance when referencing the thread. A valid thread handle must be specified. The thread handle is returned on several other interfaces.

Thread identifier. A value which uniquely identifies a thread within a job. A valid thread identifier must be specified.

User name. A specific user profile name, or blanks when the job name specified is a special value.


Error Messages



API introduced: V5R1

[ Back to top | Work Management APIs | APIs by category ]