List Subsystem Entries (QWDLSBSE) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | List format | Input | Char(8) |
| 3 | Qualified subsystem name | Input | Char(20) |
| 4 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The List Subsystem Entries (QWDLSBSE) API lists some of the different entries in a subsystem description. See the format information for the types of entries available. QWDLSBSE replaces any data that already exists in the user space.
Other subsystem information is available through the following APIs:
- QWDRSBSD Retrieve Subsystem Information
- QWDLSJBQ List Job Queue Entries
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
- Subsystem Description Authority
- *USE
- Subsystem Description Library Authority
- *EXECUTE
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that receives the list, and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The job's library list
- List format
- INPUT; CHAR(8)
The format of subsystem entries to list. You can use one of the following format names:
SBSE0100 Routing entry list. For details, see SBSE0100 Format. SBSE0200 Communications entry list. For details, see SBSE0200 Format. SBSE0300 Remote locations entry list. For details, see SBSE0300 Format. SBSE0400 Autostart job entry list. For details, see SBSE0400 Format. SBSE0500 Prestart job entry list. For details, see SBSE0500 Format. SBSE0600 Workstation name entry list. For details, see SBSE0600 Format. SBSE0700 Workstation type entry list. For details, see SBSE0700 Format.
- Qualified subsystem name
- INPUT; CHAR(20)
The subsystem description about which to retrieve information, and the library in which the subsystem description is located. The first 10 characters contain the subsystem description name, and the second 10 characters contain the library name. You can use these special values for the library name:
*CURLIB The job's current library *LIBL The job's 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.
Format of the Generated List
The list of entries that the QWDLSBSE API returns into the user space consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section
The user area and generic header are described in User spaces. The remaining items are described in the following sections. For detailed descriptions of the fields in the tables, see Field Descriptions.
When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.
Input Parameter Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format name specified |
| 28 | 1C | CHAR(10) | Subsystem name specified |
| 38 | 26 | CHAR(10) | Subsystem library name specified |
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Subsystem name used |
| 10 | A | CHAR(10) | Subsystem library name used |
SBSE0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Routing entry sequence number |
| 4 | 4 | CHAR(10) | Routing entry program name |
| 14 | E | CHAR(10) | Routing entry program library name |
| 24 | 18 | CHAR(10) | Routing entry class name |
| 34 | 22 | CHAR(10) | Routing entry class library name |
| 44 | 2C | BINARY(4) | Maximum active routing steps |
| 48 | 30 | BINARY(4) | Routing entry pool identifier |
| 52 | 34 | BINARY(4) | Compare start position |
| 56 | 38 | CHAR(80) | Compare value |
| 136 | 88 | CHAR(10) | Routing entry thread resources affinity group |
| 146 | 92 | CHAR(10) | Routing entry thread resources affinity level |
| 156 | 9C | CHAR(10) | Routing entry resources affinity group |
SBSE0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Device |
| 10 | A | CHAR(8) | Mode |
| 18 | 12 | CHAR(10) | Communication entry job description name |
| 28 | 1C | CHAR(10) | Communication entry job description library name |
| 38 | 26 | CHAR(10) | Default user |
| 48 | 30 | BINARY(4) | Maximum active jobs |
SBSE0300 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Remote location |
| 8 | 8 | CHAR(8) | Mode |
| 16 | 10 | CHAR(10) | Remote location entry job description name |
| 26 | 1A | CHAR(10) | Remote location entry job description library name |
| 36 | 24 | CHAR(10) | Default user |
| 38 | 26 | CHAR(2) | Reserved |
| 48 | 30 | BINARY(4) | Maximum active jobs |
SBSE0400 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Autostart job name |
| 10 | A | CHAR(10) | Autostart job description name |
| 20 | 14 | CHAR(10) | Autostart job description library name |
SBSE0500 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Prestart job program name |
| 10 | A | CHAR(10) | Prestart job program library name |
| 20 | 14 | CHAR(10) | User profile name |
| 30 | 1E | CHAR(1) | Start jobs |
| 31 | 1F | CHAR(1) | Wait for job |
| 32 | 20 | BINARY(4) | Initial number of jobs |
| 36 | 24 | BINARY(4) | Threshold |
| 40 | 28 | BINARY(4) | Additional number of jobs |
| 44 | 2C | BINARY(4) | Maximum number of jobs |
| 48 | 30 | BINARY(4) | Maximum number of uses |
| 52 | 34 | BINARY(4) | Pool identifier |
| 56 | 38 | CHAR(10) | Prestart job name |
| 66 | 42 | CHAR(10) | Prestart job description name |
| 76 | 4C | CHAR(10) | Prestart job description library name |
| 86 | 56 | CHAR(2) | Reserved |
| 88 | 58 | CHAR(10) | First class name |
| 98 | 62 | CHAR(10) | First class library name |
| 108 | 6C | BINARY(4) | Number of jobs to use first class |
| 112 | 70 | CHAR(10) | Second class name |
| 122 | 7A | CHAR(10) | Second class library name |
| 132 | 84 | BINARY(4) | Number of jobs to use second class |
| 136 | 88 | CHAR(10) | Prestart job thread resources affinity group |
| 146 | 92 | CHAR(10) | Prestart job thread resources affinity level |
| 156 | 9C | CHAR(10) | Prestart job resources affinity group |
SBSE0600 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Workstation name |
| 10 | A | CHAR(10) | Job description name for workstation |
| 20 | 14 | CHAR(10) | Job description library name for workstation |
| 30 | 1E | CHAR(10) | Control job (allocation) |
| 40 | 28 | BINARY(4) | Maximum active jobs |
SBSE0700 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Workstation type |
| 10 | A | CHAR(10) | Job description name for type |
| 20 | 14 | CHAR(10) | Job description library name for type |
| 30 | 1E | CHAR(10) | Control job (allocation) |
| 40 | 28 | BINARY(4) | Maximum active jobs |
Field Descriptions
Additional number of jobs. The additional number of prestart jobs that are started when the number of prestart jobs drops below the value specified for the threshold parameter.
Autostart job description library name. The name of the library in which the job description for the autostart job entry resides.
Autostart job description name. The name of the job description for the autostart job entry about which information is being returned.
Autostart job name. The simple name of the job that is automatically started when the associated subsystem is started.
Communication entry job description library name. The name of the library in which the communications entry job description resides.
Communication entry job description name. The name of the job description used when a job is started as a result of receiving a program start request and processed through this communications entry. Possible special values follow:
| *USRPRF | The job description name that is specified in the user profile of the user that made the program start request is used for jobs that are processed through this communications entry. |
Compare start position. The starting position for the routing data comparison. The comparison between the compare value and the routing data begins with this position in the routing data character string, and the last character position compared must be less than or equal to the length of the routing data used in the comparison.
Compare value. A value that is compared with the routing data to determine whether this is the routing entry that is used for starting a routing step. The special value *ANY means that any routing data is considered a match.
Control job (allocation). How the workstations that are associated with this job entry are allocated. Possible special values follow:
| *SIGNON | The workstations are allocated when the subsystem is started if the workstation is not already in use (signed on) in another subsystem. A sign-on prompt is displayed at each workstation that is associated with this work entry. If a workstation becomes allocated to a different subsystem, interactive jobs that are associated with the workstation are allowed to enter this subsystem through the Transfer Job (TFRJOB) command. |
| *ENTER | The workstations that are associated with this work entry are not allocated when the subsystem is started. However, the interactive jobs that are associated with the workstations are allowed to enter this subsystem through the Transfer Job (TFRJOB) command. |
Default user. The name of the default user profile used for evoke requests that enter the subsystem through this entry and contain no security information. Possible special values follow:
| *NONE | No user profile is specified as the default. |
| *SYS | All user program start requests are treated the same as *NONE. For program start requests that are sent by system functions, the request runs under a predetermined user profile if a user profile is not specified on the program start request. |
Device. The name of the device description or the type of the device being used with this communications entry. Possible special values follow:
| *ALL | All communications device types are used with this communications entry. |
| *APPC | All advanced program-to-program communications devices can be used with this communications entry. |
| *ASYNC | All asynchronous communications devices can be used with this communications entry. |
| *BSCEL | All bisynchronous equivalency link communications devices can be used with this communications entry. |
| *FINANCE | All finance communications devices can be used with this communications entry. |
| *INTRA | All intrasystem communications devices can be used with this communications entry. |
| *RETAIL | All retail communications devices can be used with this communications entry. |
| *SNUF | All SNA upline facility communications devices can be used with this communications entry. |
First class library name. The name of the library in which the first class resides.
First class name. The name of one of the two classes that the prestart jobs run under. Jobs start by using the first class that is specified until the number of jobs specified for the first class is reached. After the number of jobs that are specified for the first class is reached, then jobs are started by using the second class.
Format name specified. The format name as specified in the call to the API.
Initial number of jobs. The initial number of prestart jobs that are started when the subsystem is started.
Job description library name for type. The name of the library in which the job description for this workstation type resides.
Job description library name for workstation. The name of the library in which the job description for this workstation name resides.
Job description name for type. The name of the job description that is used for jobs started through this type of workstation entry. The possible special value follows:
| *USRPRF | The job description named in the user profile of the user that signs on at this type of workstation is used for jobs started through this entry. |
Job description name for workstation. The name of the job description that is used for jobs started through this workstation name entry. The possible special value follows:
| *USRPRF | The job description named in the user profile of the user that signs on at this workstation is used for jobs started through this entry. |
Maximum active jobs. The maximum number of jobs that can be active at the same time through this entry. If the entry specifies *NOMAX, indicating that there is no maximum, this number is -1.
Maximum active routing steps. The maximum number of routing steps (jobs) that can be active at the same time through this routing entry. If the routing entry specifies *NOMAX, indicating that there is no maximum, this number is -1.
Maximum number of jobs. The maximum number of prestart jobs that can be active at the same time for this prestart job entry. If the entry specifies *NOMAX, which indicates that there is no maximum, this number is -1.
Maximum number of uses. The maximum number of requests that can be handled by each prestart job in the pool before the job is ended. If the entry specifies *NOMAX, which indicates that there is no maximum, this number is -1.
Mode. The mode name of the communications device. The possible special value follows:
| *ANY | Any available modes defined to the communications device are allocated to the subsystem. If the communications device does not have defined modes associated with it, the communications device itself is allocated to the subsystem. |
Number of jobs to use first class. The maximum number of jobs to run by using the first class. Possible special values follow:
| -3 | The system calculates how many prestart jobs use
this class.
If only one class is specified and -3 is specified, all of the jobs use that class. If two classes are specified and -3 is specified for both, the first class is the value of the maximum number of jobs field divided by two, and the second class is the value of the maximum number of jobs field minus the value that is calculated for the first class. If a specific number of jobs is specified for either class and -3 is specified for the other class, the system calculates the difference between maximum number of jobs and the specific number of jobs for the -3 designation. |
| -4 | All of the prestart jobs use the specified class. |
Number of jobs to use second class. The maximum number of jobs to run by using the second class. Possible special values follow:
| -3 | The system calculates how many prestart jobs use
this class.
If only one class is specified and -3 is specified, all of the jobs use that class. If two classes are specified and -3 is specified for both, the first class is the value of the maximum number of jobs field divided by two. The second class is the value of the maximum number of jobs field minus the value that is calculated for the first class. If a specific number of jobs is specified for either class and -3 is specified for the other class, the system calculates the difference between maximum number of jobs and the specific number of jobs for the -3 designation. |
| -4 | All of the prestart jobs use the specified class. |
Pool identifier. The name of the subsystem pool identifier in which the prestart jobs will run.
Prestart job resources affinity group. Specifies whether or not the prestart jobs started by this entry are grouped together having affinity to the same set of processors and memory. The possible values are:
| *NO | Prestart jobs will not be grouped together. They will be spread across all the available system resources. |
| *YES | Prestart jobs will be grouped together such that they will have affinity to the same system resources. |
Prestart job thread resources affinity group. Specifies whether or not secondary threads running in the prestart jobs are grouped together with the initial thread, or spread across the system resources. The possible values are:
| *SYSVAL | The thread resources affinity group and level in the QTHDRSCAFN system value will be used when the job starts. |
| *NOGROUP | Secondary threads running in the prestart job will not necessarily have affinity to the same set of processors and memory as the initial thread. They will be spread across all the available system resources. |
| *GROUP | Secondary threads running in the prestart job will all have affinity to the same set of processors and memory as the initial thread. |
Prestart job thread resources affinity level. The degree to which the system tries to maintain the affinity between threads and system resources. When the prestart jobs thread resources affinity group is *SYSVAL, this field will contain blanks. The possible special values are:
| *NORMAL | A thread will use any processor or memory in the system if the resources it has affinity to are not readily available. |
| *HIGH | A thread will only use the resources it has affinity to, and will wait until they become available if necessary. |
Prestart job description library name. The name of the library in which the job description for the prestart job entry resides.
Prestart job description name. The name of the job description that is used for the prestart job entry. The possible special value follows:
| *USRPRF | The job description that has the same name as the user profile that is used. |
Prestart job name. The name of the prestart job.
Prestart job program library name. The name of the library in which the prestart job program resides.
Prestart job program name. The program name that is used to match an incoming request with an available prestart job.
Remote location. The name of the remote location for this entry.
Remote location entry job description library name. The name of the library in which the job description resides.
Remote location entry job description name. The name of the job description used when a job is started as a result of receiving a program start request and processed through this remote location entry. Possible special values follow:
| *USRPRF | The job description name that is specified in the user profile of the user that made the program start request is used for jobs that are processed through this remote location entry. |
Reserved. An ignored field.
Routing entry class library name. The name of the library in which the routing entry class resides.
Routing entry class name. The name of the class that is used when a routing step is started through this routing entry.
Routing entry pool identifier. The pool identifier of the storage pool in which the routing entry program is run.
Routing entry program library name. The name of the library in which the routing entry program resides.
Routing entry program name. The name of the program that is started when a routing step is started through this routing entry in the subsystem description. If *RTGDTA is returned, the program name is taken from the routing data that was supplied and matched against this entry. The qualified program name will be taken from the routing data in this case, where the program name is specified in positions 37 through 46 and the library name is taken from positions 47 through 56.
Routing entry resources affinity group. Specifies whether or not the jobs using this routing entry are grouped together having affinity to the same set of processors and memory. The possible values are:
| *NO | The jobs will not be grouped together. They will be spread across all the available system resources. |
| *YES | The jobs will be grouped together such that they will have affinity to the same system resources. |
Routing entry sequence number. The sequence number of the routing entry.
Routing entry thread resources affinity group. Specifies whether or not secondary threads running in jobs that started through this routing entry are grouped together with the initial thread, or spread across the system resources. The possible values are:
| *SYSVAL | The thread resources affinity group and level in the QTHDRSCAFN system value will be used when the job starts. |
| *NOGROUP | Secondary threads will not necessarily have affinity to the same set of processors and memory as the initial thread. They will be spread across all the available system resources. |
| *GROUP | Secondary threads will all have affinity to the same set of processors and memory as the initial thread. |
Routing entry thread resources affinity level. The degree to which the system tries to maintain the affinity between threads and system resources. When the routing entry thread resources affinity group is *SYSVAL, this field will contain blanks. The possible special values are:
| *NORMAL | A thread will use any processor or memory in the system if the resources it has affinity to are not readily available. |
| *HIGH | A thread will only use the resources it has affinity to, and will wait until they become available if necessary. |
Second class library name. The name of the library in which the second class resides.
Second class name. One of the two classes that the prestart jobs run under. Jobs start by using the first class that is specified until the number of jobs specified for the first class is reached. After the number of jobs that are specified for the first class is reached, then jobs are started using the second class. The possible special value follows:
| *NONE | Only one class is used. |
Start jobs. Whether the prestart jobs are started at the time the subsystem is started. Possible special values follow:
| 1 | The prestart jobs are started at the time the subsystem is started. |
| 0 | The prestart jobs are not started at the time the subsystem is started. The Start Prestart Jobs (STRPJ) command is used to start these prestart jobs. |
Subsystem library name specified. The name or special value specified in the call to this API for the library in which the subsystem description resides.
Subsystem library name used. The name of the library in which the subsystem description resides.
Subsystem name specified. The name of the subsystem specified in the call to this API.
Subsystem name used. The name of the subsystem about which information is being returned.
Threshold. The number at which additional prestart jobs are started. When the pool of available jobs (jobs available to service a program start request) is reduced below this number, more jobs (specified on the additional number of jobs field) are started and added to the available pool. This number is checked after a prestart job is attached to a procedure start request.
User profile name. The name of the user profile under which the prestart job runs.
User space library name specified. The name specified for the library that contains the user space to receive the generated list.
User space name specified. The name specified for the user space that is to receive the generated list.
Wait for job. Whether requests wait for a prestart job to become available or are rejected if a prestart job is not immediately available when the request is received. Possible special values follow:
| 1 | Requests wait until there is an available prestart job, or until a prestart job is started, to handle the request. |
| 0 | Requests are rejected if a prestart job is not immediately available when the request is received. |
Workstation name. The name of the workstation that is used by the subsystem. A generic workstation entry like DSP* is allowed.
Workstation type. The display device type. (See the TYPE
keyword in the Communications Configuration manual, SC41-5401. This manual is not included in this release of the IBM® i Information Center; however, it is available from the IBM Publications Center
as a printed hardcopy that you can order or in an online format that you can download at no charge.)
Possible special values follow:
| *ALL | All workstation devices. This includes devices with 5250, ASCII, and 327x device types. |
| *ASCII | ASCII display station. |
| *NONASCII | All workstation devices that use a 5250 data stream. This includes the 327x device types. |
| *CONS | System console display. This entry overrides a device type entry that specifies the same device type as the device being used as the console. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1605 E | Cannot allocate subsystem description &1. |
| CPF1606 E | Error during allocation of subsystem &1. |
| CPF1607 E | Previous request pending for subsystem &1. |
| CPF1608 E | Subsystem description &1 not found. |
| CPF1619 E | Subsystem description &1 in library &2 damaged. |
| CPF1835 E | Not authorized to subsystem description. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF811A E | User space &4 in &9 damaged. |
| CPF8122 E | &8 damage on library &4. |
| 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. |
| 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. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9838 E | User profile storage limit exceeded. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V3R7