Retrieve Program Information (QCLRPGMI) API

The Retrieve Program Information (QCLRPGMI) API lets you retrieve program information and place it into a single variable in the calling program. The amount of information returned is limited to the size of the variable. This information is the same as the information returned using the Display Program (DSPPGM) command.

You can use the QCLRPGMI API to retrieve the following:

• Program creation information
• Program statistics
• Program performance information
• SQL statement information
• ILE program size information

Authorities and Locks

Library Authority

*EXECUTE

Program Authority

*READ

Program Lock

*SHRRD

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. The minimum size for this area is 8 bytes. You can specify the size of this 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.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the results may not be predictable. The minimum value is 8.

Format name

INPUT; CHAR(8)

The content and format of the information returned for the program.

The possible format names are:

PGMI0100	Basic program information for OPM and ILE programs.
PGMI0200	Basic program information for OPM and ILE programs plus SQL statement information for OPM programs.
PGMI0300	ILE program size information.

Qualified program name

INPUT; CHAR(20)

The first 10 characters contain the program name. The second 10 characters contain the name of the library where the program is located.

You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Error code

I/O; CHAR(*)

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

PGMI0100 Format

The following information is returned for the PGMI0100 format. Some of the fields returned are blank or zero if they do not apply to the type of program specified. For detailed descriptions of the fields in the table, see Field Descriptions.

PGMI0200 Format

The following information is returned for the PGMI0200 format. Some of the fields returned are blank or zero if they do not apply to the type of program specified. For detailed descriptions of the fields in the table, see Field Descriptions.

PGMI0300 Format

The following information is returned for the PGMI0300 format. This format is valid only for ILE programs. If an OPM program is specified, no data is returned and an error is returned. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

For more detailed information than that provided in the following field descriptions, refer to documentation for the command that was used to create the program. For information on non-SQL fields, this would normally be one of the following:

• One of the create program (CRTxxxPGM) commands described in the programmer's guide for the language, identified by the xxx in the command name.
• The Create Program (CRTPGM) command.

For information on SQL fields, (this would normally be a command of the form CRTSQLxxx) see DB2 Universal Database for iSeries SQL Programming Concepts. The xxx in the command name identifies the base language (RPG, COBOL, and so on) of the program.

Activation group attribute. The activation group attribute of this ILE program.

Possible values are:

All creation data. Whether the ILE program has all creation data and if that data is observable or unobservable. All observable creation data is needed to re-create the program using the Change Program (CHGPGM) command. All creation data (either observable or unobservable) is needed to convert the program during restore.

Possible values are:

Allow blocking. Whether blocking is used to improve the performance of certain SQL statements.

Possible values are:

Allow copy of data. Whether a copy of the data can be used in the implementation of an SQL query.

Possible values are:

Allow RTVCLSRC. The compiler allowed you to control this attribute through the ALWRTVSRC parameter if this program was created using the Create CL Program (CRTCLPGM) command.

Possible values are:

Source that is saved can be retrieved by using the Retrieve CL Source (RTVCLSRC) command. This information is blank if the program is not a CL program.

Allow static storage reinitialization. Whether program static storage can be reinitialized. The values are valid for ILE programs only.

Possible values are:

Allow bound *SRVPGM library name update. Whether the Update Program (UPDPGM) command is allowed to change the bound *SRVPGM library names on this program. The values are valid for ILE programs only.

Possible values are:

Allow update. Whether the Update Program (UPDPGM) command is allowed on this program. The values are valid for ILE programs only.

Possible values are:

Associated space size. The size (in bytes) of the associated space used by this program.

Automatic storage size. The size (in bytes) of the automatic storage used by this program. This information is blank if the program is an ILE program.

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.

Clear program automatic storage area (PASA). The compiler may have allowed you to control this attribute through the GENOPT parameter of the command used to create the program.

Possible values are:

*NOCLRPASA reduces the time needed to call the program. However, if a program variable is referred to before it has been set, it may contain unpredictable data.

*CLRPASA increases the time needed to call the program. However, it ensures that if a program variable is referred to before it has been set, it will contain binary zeros instead of unpredictable data.

Close SQL cursor. Specifies when SQL cursors are implicitly closed and SQL-prepared statements are implicitly discarded.

Possible values are:

Commitment control. The level of commitment control that was specified on the SQL precompile.

Possible values are:

Compiler identification. The licensed program identifier, version, release, and modification level of the compiler. The field has a pppppppbVvRrMm format, where:

For programs created by the Create Program (QPRCRTPG) API, this field identifies the version of the operating system that the program was created under.

The field may be blank if the program is created without going through a compilation process or if it is an ILE program.

Connection method. The method used for establishing remote connections when running distributed programs.

Special values that can be returned are:

Conversion required. Indicates whether the program has been converted to reduced instruction-set computer (RISC) format or if conversion is still required.

Possible values are:

Creation date and time. The date and time the program was created. The creation date and time field is in the CYYMMDDHHMMSS format as follows:

Current copyright string size. The ILE program's copyright string size.

Current number of auxiliary storage segments. The number of auxiliary storage segments in this ILE program.

Current number of modules. The number of modules bound into this ILE program.

Current number of service programs. The number of service programs bound to this ILE program.

Current string directory size. The ILE program's string directory size.

Current total program size. The total size of the ILE program, in kilobytes.

Date format. The format used when accessing date-result columns through SQL. All output date fields are returned in this format. For input date strings, the value you specify is used to determine whether the date is a valid format. This information is blank if the program does not contain SQL statements or if it is an ILE program.

Possible values are:

Date separator. The separator used when accessing date-result columns. This information is blank if the program does not contain SQL statements or if it is an ILE program. However, the number of SQL statements field should be checked to determine if the program contains SQL statements. This is because a blank may be specified as a separator value.

Default collection name. The collection name used for the unqualified names of tables, views, indexes, and SQL packages.

Possible values are:

Delay PREPARE. Whether SQL prepare processing can be delayed until the statement is actually used.

Possible values are:

Dynamic user profile. The user profile used for dynamic SQL statements.

The following special values can be returned:

Earliest release program can run. The version, release, and modification level of the earliest release the program is allowed to run on. The compiler may have allowed you to control this through the TGTRLS parameter of the command used to create the program. The field has a VvRrMm format, where:

Fix decimal data. Whether decimal data that is not valid is corrected or an error is signaled. If the System/36 environment is loaded on your system, you can control this attribute through the fix decimal data (FIXDECDTA) parameter of the CRTS36CBL or CRTS36RPG command.

Possible values are:

Language identifier. Returns the 3-character language identifier used when the program was compiled. This information is blank if the module does not contain any language identification information.

The following special value can also be returned:

Log commands. The value specified for the LOG parameter of the CRTCLPGM command. This field is meaningful only if the program is a CL program. The possible values are N (*NO), Y (*YES), and J (*JOB). This information is blank if the program is not a CL program.

Maximum copyright string size. The maximum size of the copyright string in an ILE program.

Maximum number of auxiliary storage segments. The maximum number of auxiliary storage segments an ILE program can have.

Maximum number of modules. The maximum number of modules that can be bound into an ILE program.

Maximum number of parameters. The maximum number of parameters that may be received by the program when it is called. A value of -1 is returned if the information is not available.

Maximum number of service programs. The maximum number of service programs that can be bound to an ILE program.

Maximum program size. The maximum size that an ILE program can be, in kilobytes.

Maximum static storage size. The maximum static storage size (in bytes) that this program may need in order to run. A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this case, the maximum static storage size - long field should be used instead.

Maximum static storage size - long. The maximum static storage size in bytes that this program may need in order to run.

Maximum string directory size. The maximum size that the string directory can be in an ILE program.

Minimum number of parameters. The minimum number of parameters that is to be received by the program when it is called. A value of -1 is returned if the information is not available.

Minimum static storage size. The minimum static storage size in bytes that this program needs in order to run. A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this case, the minimum static storage size - long field should be used instead.

Minimum static storage size - long. The minimum static storage size in bytes that this program needs in order to run.

Naming convention. The convention used for naming objects in SQL statements.

Possible values are:

Number of copyrights. The number of copyrights in this ILE program. This field is zero if the program is an OPM program. Do not assume that a value of zero indicates that the program is an OPM program. ILE programs may not have any copyrights, so this value could be zero for an ILE program. Check the type of program field to determine whether the program is an OPM program or an ILE program.

Number of MI instructions. The number of machine interface (MI) instructions used by this program. A value of -1 is returned if the program is not observable. This information is zero if the program is an ILE program.

Number of MI ODT entries. The number of ODT (object definition table) entries for the program. This is the number of program objects declared by the compiler. Program objects include variables, constants, labels, operand lists, and exception descriptions. Typically, one or more ODT entries are used for each variable, constant, and label in your program. Some are used by the compiler for internal purposes. The number of internal ODT entries varies depending on the size and complexity of the program. There is a limit of 32 767 ODT entries in a program. A value of -1 is returned if the program is not observable. This information is zero if the program is an ILE program.

Number of modules. The number of modules bound into this program. This information is zero if the program is an OPM program.

Number of service programs. The number of service programs bound to this program. This information is zero if the program is an OPM program. Do not assume that a value of zero indicates that the program is an OPM program. ILE programs may not have any service programs bound to them, so this value could be zero for an ILE program. Check the type of program field to determine whether the program is an OPM program or an ILE program.

Number of SQL statements. The number of SQL statements contained in the program. This value is zero if the program does not contain SQL statements or if it is an ILE program.

Number of unresolved references. The number of symbols that could not be resolved at Create Program (CRTPGM) command time. This information is always zero if the program is an OPM program. If this is an ILE program, and if all references were resolved at the time the program was created, this value for this field could be zero.

Observable information. Whether the OPM program contains creation data and if that data is observable or unobservable. All observable creation data is needed to re-create the program using CHGPGM. All creation data (either observable or unobservable) is needed to convert the program during restore.

Possible values are:

The observable information for most programs may be removed by using the remove observability (RMVOBS) parameter on the Change Program (CHGPGM) command.

Observable information compressed. Whether the observable information associated with the program is compressed.

Possible values are:

Optimization. Indicates what was specified on the OPTIMIZE parameter when the program was created or changed.

Possible values are:

Paging amount. The compiler may have allowed you to control this attribute through the GENOPT parameter of the command used to create the program.

Possible values are:

*BLOCK gives better performance in most situations. It is likely that more than one page in the block is referred to before being replaced by some other paging occurring in the storage pool.

*NOBLOCK can give better performance if the other pages that would have been brought in as a block are unlikely to be referred to before being replaced by some other paging.

Paging pool. The paging pool used for the program object. The compiler may have allowed you to control this attribute through the GENOPT parameter of the command used to create the program.

The values returned are:

*USER is used by most system programs and all user programs, unless GENOPT(*MACHINE) is specified.

*BASE is used by certain system programs to avoid disturbing the user pool when they need to be paged in. These programs are not used frequently enough to belong in the machine pool. This value will only appear for OPM programs.

*MACHINE is used by a small number of system programs that are so highly used that their pages should remain almost constantly in main storage. The machine pool is intended to be a stable, low paging pool. If user programs page in the machine pool, there may be contention for main storage between system and user programs. This may adversely affect system performance and response times. To prevent paging contention, increase the QMCHPOOL system value with the Change System Value (CHGSYSVAL) command.

Profiling data. Specifies the profiling data attribute for this ILE program.

Possible values are:

Program attribute. The language the program is written in. (For example, the value is CLP for a CL program, and the value is RPG for an RPG program). This field can be blank. (For example, the program was created by the Create Program (QPRCRTPG) API or the program is created by a compilation process internal to IBM).

Program CCSID. The coded character set identifier (CCSID) for this ILE program. This is 65535 for ILE programs. This information is zero if the program is an OPM program.

Program domain. The domain of the program.

Possible values are:

Program entry procedure module. The module name that contains the program entry procedure for this program. This information is blank if the program is an OPM program.

Program entry procedure module library. The library name that contained the module that contained the program entry procedure for this program when the bind was done. This information is blank if the program is an OPM program.

Program library name. The name of the library containing the program.

Program name. The name of the program.

Program owner. The name of the program owner's user profile.

Program size. The size (in bytes) of this program.

Program state. The state of the program.

Possible values are:

Relational database. The default relational database that was specified on the SQL precompile. A nonblank value other than *LOCAL specifies the name of the relational database to be resolved through the relational database directory.

The following special values can be returned:

Release program created for. This is the release specified on the target release (TGTRLS) parameter of the Create Program (CRTPGM) command. The value specified for the TGTRLS parameter can affect the earliest release value on which the program can run.

Release program created on. The version, release, and modification level of the operating system on which the program was created.

Reserved. An ignored field.

Run-time information compressed. Whether the run-time information associated with the program is compressed.

Possible values are:

Shared activation group. Whether the program runs in a shared activation group.

Sort sequence table library name. The name of the library the sort sequence table is in.

This information is blank if the program does not contain any sort sequence information or a special value was returned for the sort sequence table name.

The following special values can be returned:

Sort sequence table name. The name of the sort sequence table used when the program was compiled. This does not apply to SQL statements in the program.

The following special values can be returned:

Source file library name. The name of the library that contains the source file used to create the program. The field is blank if a source file was not used to create the program or if it is an ILE program.

Source file member name. The name of the member in the source file. The field is blank if a source file was not used to create the program or if it is an ILE program.

Source file name. The name of the source file used to create the program. The field is blank if a source file was not used to create the program or if it is an ILE program.

Source file updated date and time. The date and time the member in the source file was last updated. The field is in the same format as the creation time and date. The field is blank if a source file was not used to create the program or if it is an ILE program.

SQL package library name. The name of the library the SQL package is in.

SQL package name. The name of the SQL package created on the relational database specified on the RDB parameter of the command that created this program.

SQL path. The list of libraries used during resolution of functions, procedures, and data types within SQL statements. The list is in the form of repeating library names, each surrounded by double quotes and separated by commas.

SQL path length. The length, in bytes, of the SQL path.

SQL path offset. The offset, in bytes, from the beginning of this format definition to the beginning of the SQL path.

SQL sort language identifier. The 3-character language identifier used when the program was compiled. This information is blank if the program does not contain any language identification information.

The following possible special value can be returned:

SQL sort sequence table name. The SQL sort sequence table returns the SQL sort sequence table name used when the program was compiled. This information is blank if the program does not contain any SQL sort sequence information or if this is an ILE program.

The following special values can be returned:

SQL sort sequence table library name. The name of the library the SQL sort sequence table is in. This information is blank if the program does not contain any SQL sort sequence information or a special value was returned for the SQL sort sequence table name.

The following special values can be returned:

Static storage size. For OPM programs this is the size (in bytes) of the static storage used by the program. For ILE programs this is the maximum amount of static storage (in bytes) that may be needed to run the program. A value of 4294967295 will be given if 4 gigabytes (4294967296) or greater is needed. In this case, the maximum static storage size - long field should be used instead. The maximum static storage size - long field is available from the PGMI0300 format. OPM programs will always have less than 4 gigabytes of static storage.

Storage model. Where the automatic and static storage for this program is allocated at run time.

The following values can be returned:

Teraspace storage enabled modules. The teraspace storage capability of the modules bound to this program.

Possible values are:

Teraspace storage enabled program. The teraspace storage capability of an OPM program. A program must be teraspace storage enabled to access teraspace storage.

Possible values are:

Text description. The user text, if any, used to briefly describe the program and its function.

Time format. The format used when accessing time-result columns through SQL. All output time fields are returned in this format.

Possible values are:

Time separator. The separator used when accessing time-result columns. This information is blank if the program does not contain SQL statements or if it is an ILE program. However, the number of SQL statements is checked to determine if the program contains SQL statements. This is because a blank may be specified as a separator value.

Type of program. Whether the program is an ILE program or an OPM program.

Possible values are:

Update program automatic storage area (PASA). The compiler may have allowed you to control this attribute through the GENOPT parameter of the command used to create the program. This information is blank if the program is an ILE program.

Possible values are:

*NOUPDPASA reduces the time needed to call the program.

*UPDPASA increases the time needed to call the program but is used by some system programs that are dependent on updates of internal PASA stack information.

Use adopted authority. The value specified for the USEADPAUT option on the command used to change the program.

Possible values are:

User profile option. The value specified for the USRPRF option on the command used to create the program.

Possible values are:

Error Messages