Retrieve Service Program Information (QBNRSPGM) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified service program name | Input | Char(20) |
| 5 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Service Program Information (QBNRSPGM) API lets you retrieve service 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 similar to the information returned using the Display Service Program (DSPSRVPGM) command.
The QSYS2.PROGRAM_INFO view can be used as an alternative to this API. See PROGRAM_INFO view for more information.
You can use the QBNRSPGM API to retrieve the following:
- Service program creation information
- Service program statistics
- Service program performance information
- Service program size information
Authorities and Locks
- Library Authority
- *EXECUTE
- Service Program Authority (see note)
- *READ
- Service Program Lock
- *SHRRD
Note:You must have *USE service program authority to retrieve the following fields in the SPGI0100 format:
- Export source file name
- Export source file library name
- Export source file member name
Export source stream file
If you attempt to retrieve these fields with *READ service program authority, they are set to blanks. All other fields in the SPGI0100 format require *READ service program authority.
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 if you specify the length of receiver variable 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 service program.
The possible format names are:
SPGI0100 Basic service program information. SPGI0200 Service program size information.
- Qualified service program name
- INPUT; CHAR(20)
The first 10 characters contain the service program name. The second 10 characters contain the name of the library where the service 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.
SPGI0100 Format
The following information is returned for the SPGI0100 format. See Authorities and Locks for the authority needed regarding specific fields. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| Service program creation information | |||
| 8 | 8 | CHAR(10) | Service program name |
| 18 | 12 | CHAR(10) | Service program library name |
| 28 | 1C | CHAR(10) | Service program owner |
| 38 | 26 | CHAR(10) | Service program attribute |
| 48 | 30 | CHAR(13) | Creation date and time |
| 61 | 3D | CHAR(10) | Export source file name |
| 71 | 47 | CHAR(10) | Export source file library name |
| 81 | 51 | CHAR(10) | Export source file member name |
| 91 | 5B | CHAR(30) | Activation group attribute |
| 121 | 79 | CHAR(16) | Current export signature |
| 137 | 89 | CHAR(1) | User profile |
| 138 | 8A | CHAR(1) | Observable information compressed |
| 139 | 8B | CHAR(1) | Run-time information compressed |
| 140 | 8C | BINARY(4) | Service program CCSID |
| 144 | 90 | BINARY(4) | Number of modules |
| 148 | 94 | BINARY(4) | Number of service programs |
| 152 | 98 | BINARY(4) | Number of copyrights |
| 156 | 9C | CHAR(50) | Text description |
| 206 | CE | CHAR(1) | Shared activation group |
| 207 | CF | CHAR(1) | Allow update |
| 208 | D0 | BINARY(4) | Number of unresolved references |
| 212 | D4 | CHAR(1) | Use adopted authority |
| 213 | D5 | CHAR(1) | Allow bound *SRVPGM library name update |
| 214 | D6 | CHAR(10) | Profiling data |
| 224 | E0 | CHAR(1) | Teraspace storage enabled modules |
| 225 | E1 | CHAR(1) | Storage model |
| 226 | E2 | CHAR(10) | Uses argument optimization (ARGOPT) |
| 236 | EC | CHAR(70) | Reserved '00'X |
| Service program statistics information | |||
| 306 | 132 | CHAR(1) | Service program state |
| 307 | 133 | CHAR(1) | Service program domain |
| 308 | 134 | BINARY(4) | Associated space size |
| 312 | 138 | BINARY(4) | Static storage size |
| 316 | 13C | BINARY(4) | Service program size |
| 320 | 140 | CHAR(6) | Release service program created on |
| 326 | 146 | CHAR(6) | Earliest release service program can run |
| 332 | 14C | CHAR(6) | Release service program created for |
| 338 | 152 | CHAR(1) | Allow static storage reinitialization |
| 339 | 153 | CHAR(1) | Conversion required |
| 340 | 154 | CHAR(1) | All creation data |
| 341 | 155 | CHAR(1) | Conversion details |
| 342 | 156 | CHAR(90) | Reserved |
| Service program performance information | |||
| 432 | 1B0 | CHAR(1) | Paging pool |
| 433 | 1B1 | CHAR(1) | Paging amount |
|
Path name to the export source stream file
|
|||
|
434 |
1B2 | CHAR(2) | Reserved
|
|
436 |
1B4 | BINARY(4) | CCSID of the path name to the export source
stream file |
|
440 |
1B8 | BINARY(4) | Length of path name to the export source
stream file |
|
444 |
1BC | CHAR(5000) | Path name to the export source stream file
|
SPGI0200 Format
The following information is returned for the SPGI0200 format. For detailed descriptions of the fields in the table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| Service program size information | |||
| 8 | 8 | CHAR(10) | Service program name |
| 18 | 12 | CHAR(10) | Service program library name |
| 28 | 1C | BINARY(4) | Current total service program size |
| 32 | 20 | BINARY(4) | Maximum service program size |
| 36 | 24 | BINARY(4) | Current number of modules |
| 40 | 28 | BINARY(4) | Maximum number of modules |
| 44 | 2C | BINARY(4) | Current number of service programs |
| 48 | 30 | BINARY(4) | Maximum number of service programs |
| 52 | 34 | BINARY(4) | Current string directory size |
| 56 | 38 | BINARY(4) | Maximum string directory size |
| 60 | 3C | BINARY(4) | Current copyright string size |
| 64 | 40 | BINARY(4) | Maximum copyright string size |
| 68 | 44 | BINARY(4) | Current number of auxiliary storage segments |
| 72 | 48 | BINARY(4) | Maximum number of auxiliary storage segments |
| 76 | 4C | BINARY(4) | Current number of program procedure exports |
| 80 | 50 | BINARY(4) | Maximum number of program procedure exports |
| 84 | 54 | BINARY(4) | Current number of program data exports |
| 88 | 58 | BINARY(4) | Maximum number of program data exports |
| 92 | 5C | BINARY(4) | Current number of signatures |
| 96 | 60 | BINARY(4) | Maximum number of signatures |
| 100 | 64 | BINARY(4) | Minimum static storage size |
| 104 | 68 | BINARY(4) | Maximum static storage size |
| 108 | 6C | CHAR(4) | Reserved |
| 112 | 70 | BINARY(8) | Minimum static storage size - long |
| 120 | 78 | BINARY(8) | Maximum static storage size - long |
Field Descriptions
For more detailed information than that provided in the following field descriptions, refer to the online help for the Create Service Program (CRTSRVPGM) command.
Activation group attribute. The activation group attribute of this service program.
The possible values are:
| *CALLER | The service program runs in the activation group of the program from which it is called. |
| activation group name | The name of the activation group in which this service program runs. If the activation group already exists when the service program is called, the service program runs in the existing activation group. If the activation group does not exist when the service program is called, a new activation group is created in which the service program runs. |
All creation data. Whether the ILE service program has all creation data and if that data is observable or unobservable. All observable creation data is needed to re-create the service program using the Change Service Program (CHGSRVPGM) command. All creation data (either observable or unobservable) is needed to convert the service program during restore.
Possible values are:
| 0 | *NO. Not all of the creation data is present. The creation template of the service program object could be missing or at least one of the modules in this service program does not have creation data. The Display Service Program (DSPSRVPGM) command with *MODULE specified as the value for the DETAIL parameter can be used to see whether a module has creation data. |
| 1 | *YES. The ILE service program has all creation data and all of that data is observable. |
| 2 | *UNOBS. The ILE service program has all creation data but not all of that data is observable. |
Allow static storage reinitialization. Whether service program static storage can be reinitialized.
The possible values are:
| Y | Program static storage can be reinitialized. |
| N | Program static storage cannot be reinitialized. |
Allow bound *SRVPGM library name update. Whether the Update Service Program (UPDSRVPGM) command is allowed to change the bound *SRVPGM library names on this service program.
Possible values are:
| Y | The UPDSRVPGM command can specify a library name for the SRVPGMLIB parameter. |
| N | The UPDSRVPGM command cannot specify a library name for the SRVPGMLIB parameter. |
Allow update. Whether the Update Service Program (UPDSRVPGM) command is allowed on this service program.
Possible values are:
| Y | The UPDSRVPGM command can be run on this service program. |
| N | The UPDSRVPGM command cannot be run on this service program. |
Associated space size. The size (in bytes) of the associated space used by this service 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.
CCSID of the path name
to the export source stream file. Coded character set ID of the
path name to the export source stream file field. If the
path name to the export source stream file field is not used,
the value contained in this field is undefined.
Conversion details. Indicates details about the service program's conversion status.
Possible values are:
| 0 | *FORMAT. The service program is not compatible because it is in an older format. |
| 1 | *FEATURE. The service program is not compatible. The format is current, but the service program requires features not present on the current machine implementation. |
| 2 | *COMPAT. The service program is compatible, but requires features not present on all systems supported by this release. |
| 3 | *COMMON. The service program is compatible and requires only features common to all systems supported by this release. |
Conversion required. Indicates whether the service program has been converted to the format required by the machine or if conversion is still required.
Possible values are:
| 0 | Conversion is not required. The service program has been converted. |
| 1 | Conversion is required. |
Creation date and time. The date and time the service program was created. The creation date and time field is in the CYYMMDDHHMMSS format as follows:
| C | Century, where 0 indicates years 19xx and 1 indicates years 20xx. |
| YY | Year |
| MM | Month |
| DD | Day |
| HH | Hour |
| MM | Minute |
| SS | Second |
Current copyright string size. The size of the service program's copyright string.
Current export signature. The current export signature of this service program.
Current number of auxiliary storage segments. The number of auxiliary storage segments in this service program.
Current number of modules. The number of modules bound into this service program.
Current number of program data exports. The number of data items exported from this service program.
Current number of program procedure exports. The number of procedures exported from this service program.
Current number of service programs. The number of service programs bound to this service program.
Current number of signatures. The number of signatures for this service program.
Current string directory size. The service program's string directory size.
Current total service program size. The total size of the service program, in kilobytes.
Earliest release service program can run. The version, release, and modification level of the earliest release on which the service program is allowed to run. The field has a VvRrMm format, where:
| Vv | The character V is followed by a 1-character version number. |
| Rr | The character R is followed by a 1-character release level. |
| Mm | The character M is followed by a 1-character modification level. |
Export source file library name. The name of the library that contains the export source file. This may be blank if:
- No export source file was specified on the CRTSRVPGM command.
- You attempt to retrieve this field with a service program authority of *READ. A service program authority of *USE is required.
- The export source was
specified with the Export source stream file
(SRCSTMF) parameter.
Export source file member name. The name of the member in the export source file that was used to create this service program. This may be blank if:
- No export source file was specified on the CRTSRVPGM command.
- You attempt to retrieve this field with a service program authority of *READ. A service program authority of *USE is required.
- The export source was
specified with the Export source stream file
(SRCSTMF) parameter.
Export source file name. The name of the export source file that contains the export source file member.
The possible values are:
| Source file name | The name of the file that contains the export source file member. |
| Blanks | No export source file was specified or an attempt was made to retrieve this field with a service program authority of *READ. A service program authority of *USE is required. |
| *STMF | The export source file was specified with the
SRCSTMF parameter. In this case, the path name to a stream file
is contained in the path name to the export source
stream file field. |
Length of path
name to the export source stream file.
Specifies the number of bytes defined in the path name to the
export source stream file field. If the export source
file name field does not contain the special value of *STMF,
then this field is set to zero.
Maximum copyright string size. The maximum size of the copyright string in a service program.
Maximum number of auxiliary storage segments. The maximum number of auxiliary storage segments a service program can have.
Maximum number of modules. The maximum number of modules that can be bound into a service program.
Maximum number of program data exports. The maximum number of data items that can be exported by a service program.
Maximum number of program procedure exports. The maximum number of procedures that can be exported by a service program.
Maximum number of service programs. The maximum number of service programs that can be bound to a service program.
Maximum number of signatures. The maximum number of signatures that can be in a service program.
Maximum service program size. The maximum size of a service program, in kilobytes.
Maximum static storage size. The maximum amount of static storage in bytes that may be needed to run the service 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.
Maximum static storage size - long. The maximum amount of static storage in bytes that may be needed to run the service program.
Maximum string directory size. The maximum size of the string directory in a service program, in bytes.
Minimum static storage size. The minimum amount of static storage, in bytes, needed to run the service program. 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 amount of static storage in bytes needed to run the service program.
Number of copyrights. The number of copyrights in this service program.
Number of modules. The number of modules bound into this service program.
Number of service programs. The number of service programs bound to this program.
Number of unresolved references. The number of symbols that could not be resolved at Create Service Program (CRTSRVPGM) command time. This number could be zero if all references were resolved at the time the service program was created.
Observable information compressed. Whether the observable information associated with the service program is compressed.
The possible values are:
| Y | The observable information is compressed. |
| N | The observable information is not compressed. |
Paging amount. The compiler may have allowed you to control this attribute through the GENOPT parameter of the CRTSRVPGM command.
Possible values are:
| N | Page the program one page at a time (*NOBLOCK). |
| B | Page the program in eight-page blocks (*BLOCK). |
*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 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 other paging.
Paging pool. The paging pool used for the service program object. The compiler may have allowed you to control this attribute through the GENOPT parameter of the CRTSRVPGM command.
The values returned are:
| U | Use the user pool (*USER). |
| M | Use the machine pool (*MACHINE). |
*USER is used by most system service programs and all user service programs unless GENOPT(*MACHINE) is specified.
*MACHINE is used by a few system service 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 service programs page in the machine pool, there may be contention for main storage between system and user service 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.
Path name to
the export source stream file. The path name
of the stream file that contains the export source for this service program.
The length of the path name to the export source stream file
field contains the number of bytes that make up the path name in this field.
The remaining bytes in the field are undefined. The CCSID of the path name
in this field is contained in the CCSID of the path name to the export
source stream file field. This field contains a path name only if
the export source file name field contains a special value
of *STMF. Otherwise, the value contained in this field is undefined.
Profiling data. The profiling data attribute for this service program.
Possible values are:
| *NOCOL | The collection of profiling data is not enabled and profiling data is not applied. |
| *COL | The collection of profiling data is enabled for at least one module bound into this service program. Any applied profiling data has been removed. The QBNLSPGM API, format SPGL0100, can be used to determine if a module bound into this service program is enabled to collect profiling data. |
| *APYBLKORD | Block-order profiling data has been applied to at least one module bound into this service program. The QBNLSPGM API, format SPGL0100, can be used to determine if a module bound into this service program has block-order profiling data applied. |
| *APYPRCORD | Procedure-order profiling data has been applied to this service program. |
| *APYALL | Block-order and procedure-order profiling data have been applied to this service program. |
Release service program created for. This is the release specified on the target release (TGTRLS) parameter of the Create Service Program (CRTSRVPGM) command. The value specified for the TGTRLS parameter can affect the earliest release value on which the program can run.
Release service program created on. The version, release, and modification level of the operating system on which the service program was created. The field has a VvRrMm format, where:
| Vv | The character V is followed by a 1-character version number. |
| Rr | The character R is followed by a 1-character release level. |
| Mm | The character M is followed by a 1-character modification level. |
Reserved. An ignored field.
Run-time information compressed. Whether the run-time information associated with the service program is compressed.
Possible values are:
| Y | The run-time information is compressed. |
| N | The run-time information is not compressed. |
Service program attribute. The language the program is written in (for example, RPG.)
Service program CCSID. The coded character set identifier (CCSID) for this service program. This is 65535 for service programs.
Service program domain. The domain of the service program.
Possible values are:
| S | The service program can be called by system-state programs. |
| U | The service program can be called by user- or system-state programs. |
Service program library name. The name of the library containing the service program.
Service program name. The name of the service program.
Service program owner. The name of the service program owner's user profile.
Service program size. The size (in bytes) of this service program.
Service program state. The state of the service program.
Possible values are:
| I | The service program runs under (inherits) the same state as its caller. |
| S | The service program can call user- or system-state programs. |
| U | The service program can call user-state programs. |
Shared activation group. Whether the service program runs in a shared activation group.
| Y | The activation group is shared. |
| N | The activation group is not shared. |
Static storage size. The maximum amount of static storage in bytes that may be needed to run the service 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. The maximum static storage size - long field is available from the SPGI0200 format.
Storage model. Where the automatic and static storage for this service program is allocated at run time.
The following values can be returned:
| 0 *SNGLVL | Automatic and static storage are allocated from single-level storage. |
| 1 *TERASPACE | Automatic and static storage are allocated from teraspace. |
| 2 *INHERIT | Automatic and static storage are allocated from either single-level storage or teraspace, depending on the activation. |
Teraspace storage enabled modules. The teraspace storage capability of the modules bound to this service program.
Possible values are:
| '00'X | No modules bound to this service program are teraspace storage enabled. |
| '80'X | One or more modules bound to this service program are teraspace storage enabled. |
| 'A0'X | All modules bound to this service program are teraspace storage enabled. However, if this object is taken back to a release prior to V6R1M0, not all bound modules may be teraspace enabled. |
Text description. The user text, if any, used to briefly describe the service program and its function.
Use adopted authority. The value specified for the USEADPAUT option on the command used to change the service program.
Possible values are:
| Y | Uses program adopted authority from previous call levels when this service program is running (*YES). |
| N | Does not use program adopted authority from previous call levels when this service program is running (*NO). |
User profile. The value specified for the USRPRF option on the CRTSRVPGM command.
Possible values are:
| U | The service program runs under the current user's user profile (*USER). |
| O | The service program runs under both the current user's and the owner's user profiles (*OWNER). |
Uses argument optimization (ARGOPT). Whether argument optimization was done during service program creation.
Possible values are:
| *YES | Argument optimization was performed during service program creation. |
| *NO | Argument optimization was not performed during service program creation. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2150 E | Object information function failed. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C20 E | Error found by program &1. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF8122 E | &8 damage on library &4. |
| CPF8123 E | Damage on object information for library &4. |
| CPF813D E | Service program &4 in &9 damaged. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9806 E | Cannot perform function for object &2 in library &3. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R3
[ Back to top | Program and CL Command APIs | APIs by category ]