| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of receiver information | Input | Char(8) |
| 4 | Job identification information | Input | Char(*) |
| 5 | Format of job identification information | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
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.
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.
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.
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.
The format of the information returned in the receiver variable. The possible format name is:
| CSTK0100 | See Format CSTK0100 for details on the call stack information returned. |
| CSTK0200 | See Format CSTK0200 for details on the call stack information returned. The format data will contain OPM, ILE, IBM® i PASE, and Java™ program stack frames. |
| CSTK0300 | See Format CSTK0300 for details on the call stack information returned. The format data 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. |
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.
The format of the job identification information. The possible format names are:
| JIDF0100 | See JIDF0100 Format for details on the job identification information. |
| JIDF0200 | See JIDF0200 Format for details on the job identification information. |
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
This format will contain OPM and ILE stack frames. For details about the fields listed, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of call stack entries for thread |
| 12 | C | BINARY(4) | Offset to call stack entry information |
| 16 | 10 | BINARY(4) | Number of call stack entries returned |
| 20 | 14 | CHAR(8) | Returned thread identifier |
| 28 | 1C | CHAR(1) | Information status |
| 29 | 1D | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Length of this call stack entry | |
| BINARY(4) | Displacement to statement identifiers | ||
| BINARY(4) | Number of statement identifiers | ||
| BINARY(4) | Displacement to the procedure name | ||
| BINARY(4) | Length of procedure name | ||
| BINARY(4) | Request level | ||
| CHAR(10) | Program name | ||
| CHAR(10) | Program library name | ||
| BINARY(4) | MI instruction number | ||
| CHAR(10) | Module name | ||
| CHAR(10) | Module library name | ||
| CHAR(1) | Control boundary | ||
| CHAR(3) | Reserved | ||
| BINARY(4), UNSIGNED | Activation group number | ||
| CHAR(10) | Activation group name | ||
| CHAR(2) | Reserved | ||
| CHAR(10) | Program ASP name | ||
| CHAR(10) | Program library ASP name | ||
| BINARY(4) | Program ASP number | ||
| BINARY(4) | Program library ASP number | ||
| BINARY(8), UNSIGNED | Activation group number long | ||
| CHAR(*) | Reserved | ||
| ARRAY(*) of CHAR(10) | Statement identifiers | ||
| CHAR(*) | Procedure name | ||
This format will contain OPM, ILE, IBM PASE for i, and Java program stack frames. For details about the fields listed, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of call stack entries for thread |
| 12 | C | BINARY(4) | Offset to call stack entry information |
| 16 | 10 | BINARY(4) | Number of call stack entries returned |
| 20 | 14 | CHAR(8) | Returned thread identifier |
| 28 | 1C | CHAR(1) | Information status |
| 29 | 1D | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Length of this call stack entry | |
| BINARY(4) | Displacement to call stack entry data | ||
| CHAR(8) | Format name of call stack entry data | ||
| BINARY(4) | Length of call stack entry data | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Call stack entry data (See Format of Call Stack Entry Data for more information.) | ||
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of call stack entries for thread |
| 12 | C | BINARY(4) | Offset to call stack entry information |
| 16 | 10 | BINARY(4) | Number of call stack entries returned |
| 20 | 14 | CHAR(8) | Returned thread identifier |
| 28 | 1C | CHAR(1) | Information status |
| 29 | 1D | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Length of this call stack entry | |
| BINARY(4) | Displacement to call stack entry data | ||
| CHAR(8) | Format name of call stack entry data | ||
| BINARY(4) | Length of call stack entry data | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Call stack entry data (See Format of Call Stack Entry Data for more information.) | ||
The format of the information returned for a given stack frame.
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Displacement to statement identifiers | |
| BINARY(4) | Number of statement identifiers | ||
| BINARY(4) | Displacement to the procedure name | ||
| BINARY(4) | Length of procedure name | ||
| BINARY(4) | Request level | ||
| CHAR(10) | Program name | ||
| CHAR(10) | Program library name | ||
| CHAR(10) | Module name | ||
| CHAR(10) | Module library name | ||
| BINARY(4) | MI instruction number | ||
| BINARY(8), UNSIGNED | Activation group number long | ||
| CHAR(10) | Activation group name | ||
| CHAR(1) | Control boundary | ||
| CHAR(1) | Reserved | ||
| CHAR(10) | Program ASP name | ||
| CHAR(10) | Program library ASP name | ||
| BINARY(4) | Program ASP number | ||
| BINARY(4) | Program library ASP number | ||
| CHAR(*) | Reserved | ||
| ARRAY(*) of CHAR(10) | Statement identifiers | ||
| CHAR(*) | Procedure name | ||
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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Displacement to procedure name | |
| BINARY(4) | Length of procedure name | ||
| BINARY(4) | Displacement to load module name | ||
| BINARY(4) | Length of load module name | ||
| BINARY(4) | Displacement to load module path | ||
| BINARY(4) | Length of load module path | ||
| BINARY(4) | Displacement to source path and file | ||
| BINARY(4) | Length of source path and file | ||
| BINARY(4) , UNSIGNED | Line number | ||
| BINARY(8) , UNSIGNED | Instruction address | ||
| BINARY(4) , UNSIGNED | Instruction offset | ||
| CHAR(1) | 32-bit indicator | ||
| CHAR(1) | Kernel indicator | ||
| CHAR(1) | Alternate resume point indicator | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Procedure name | ||
| CHAR(*) | Load module name | ||
| CHAR(*) | Load module path | ||
| CHAR(*) | Source path and file | ||
This format describes the data that is returned for Licensed Internal Code stack frames. For details about the fields listed, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Displacement to procedure name | |
| BINARY(4) | Length of procedure name | ||
| BINARY(4) | Displacement to load module name | ||
| BINARY(4) | Length of load module name | ||
| BINARY(4), UNSIGNED | Instruction offset | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Procedure name | ||
| CHAR(*) | Load module name | ||
This format describes the data that is returned for Java stack frames. For details about the fields listed, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed, for the number of call stack entries. | BINARY(4) | Displacement to Java class name | |
| BINARY(4) | Length of Java class name | ||
| BINARY(4) | Displacement to Java method name | ||
| BINARY(4) | Length of Java method name | ||
| BINARY(4) | Displacement to Java method signature | ||
| BINARY(4) | Length of Java method signature | ||
| BINARY(4) | Displacement to Java file name/directory | ||
| BINARY(4) | Length of Java file name/directory | ||
| BINARY(4) | Displacement to Java source file name | ||
| BINARY(4) | Length of Java source file name | ||
| BINARY(4) | Java coded character set ID | ||
| BINARY(4) | Line number | ||
| BINARY(4) | Java byte code offset | ||
| CHAR(1) | Java method type | ||
| CHAR(*) | Reserved | ||
| CHAR(*) | Java class name | ||
| CHAR(*) | Java method name | ||
| CHAR(*) | Java method signature | ||
| CHAR(*) | Java file name/directory | ||
| CHAR(*) | Java source file name | ||
32-bit indicator. Whether the invocation is running 32-bit or 64-bit IBM PASE for i code. The possible values are:
| 0 | 64-bit. |
| 1 | 32-bit. |
| blank | No information |
Activation group name. The name of the activation group within which the program or procedure is running. Possible special values are:
| *DFTACTGRP | The activation group does not have a specific name. The activation group is one of the default activation groups for the system. |
| *NEW | The activation group does not have a specific name. The activation group was created when the program was called. |
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:
| 0 | The current invocation does not have an alternate resume point. |
| 1 | The current invocation does have an alternate resume point. |
| blank | No information |
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:
| 0 | No control boundary is active. |
| 1 | A control boundary is active. |
| blank | No information |
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:
| STKE0100 | See STKE0100 Format for details on the call stack information returned. |
| STKE0200 | See STKE0200 Format for details on the call stack information returned. |
| STKE0300 | See STKE0300 Format for details on the call stack information returned. |
| STKE0400 | See STKE0400 Format for details on the call stack information returned. |
Information status. Whether the call stack entry information could be successfully retrieved.
| blank | No errors occurred. All information is returned in each entry. |
| I | The information in each entry is not complete. The request level, control boundary, activation group number and activation group name fields could not be retrieved. The request level and activation group number are zero and the control boundary and activation group name are blank in each entry. |
| N | The call stack entry information could not be retrieved. No entries are returned. |
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:
| 0 | The method is a direct execution Java method. The Java method has been precompiled by the Java Transformer. |
| 1 | The method is a JIT compiled Java method. The Java method has been compiled by the Java Just In Time Compiler. |
| 2 | The method is an interpreted Java method. The Java method is being interpreted by the Java Interpreter. |
| 3 | The method is a MMI interpreted Java method. The Java method is being interpreted by the Mixed Mode Java Interpreter. |
| 4 | The invocation is a Java Virtual Machine glue frame used either to perform a call from the JVM to a Java method or perform a call to a Java native method. |
| blank | No information. |
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:
| 0 | The current invocation is not IBM PASE for i kernel code. |
| 1 | The current invocation is IBM PASE for i kernel code. |
| blank | No information |
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:
| *N | The module library name is unavailable. Either the program has been destroyed or the library containing the program is locked. |
| blanks | The program at this call stack entry is not an ILE program. |
Module name. The module containing the integrated language environment (ILE) procedure. The following special values may be returned:
| *N | The module name is unavailable. Either the program has been destroyed or the library containing the program is locked. |
| blanks | The program at this call stack entry is not an ILE program. |
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:
| *SYSBAS | The program is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Program ASP number. The numeric identifier of the ASP containing the program. The following values may be returned:
| 1 | The library is located in the system ASP. |
| 2-32 | The library is located in a basic user ASP. |
| 33-255 | The library is located in an independent ASP. |
| -1 | The ASP device cannot be determined. |
Program library ASP name. The name of the ASP in which the program library is located. The following special values also may be returned:
| *SYSBAS | The program library is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Program library ASP number. The numeric identifier of the ASP containing the program library. The following values may be returned:
| 1 | The library is located in the system ASP or in a basic user ASP. |
| 2-32 | The library is located in a basic user ASP. |
| 33-255 | The library is located in an independent ASP. |
| -1 | The ASP device cannot be determined. |
Program library name. The name of the library in which the program is located. The following special values may be returned:
| *N | The program library name is unavailable. The library containing the program has been destroyed or is locked. |
| blanks | The program is not located in a library. |
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:
| *N | The program is unavailable. Either the program has been destroyed or the library containing the program is locked. |
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.
The format of the information needed to identify the thread for which call stack information will be returned.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4) | Thread indicator |
| 48 | 30 | CHAR(8) | Thread identifier |
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:
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
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:
| 0 | Specifies that information should be retrieved for the thread specified in the thread identifier field. |
| 1 | Specifies that information should be retrieved for the thread that this program is currently running in. The combination of the internal job identifier, job name, job number, and user name fields must also identify the job containing the current thread. |
| 2 | Specifies that information should be retrieved for the initial thread of the identified job. |
User name. A specific user profile name, or blanks when the job name specified is a special value.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4), UNSIGNED | Thread handle |
| 48 | 30 | CHAR(8) | Thread identifier |
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:
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
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.
| Message ID | Error Message Text |
|---|---|
| CPF136A E | Job &3/&2/&1 not active. |
| CPF18BF E | Thread &1 not found. |
| CPF222E E | &1 special authority is required. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C55 E | Job &3/&2/&1 does not exist. |
| CPF3C57 E | Not authorized to retrieve job information. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |