Change Subsystem Entry (QWDCSBSE) API
Required Parameter Group:
| 1 | Qualified subsystem name | Input | Char(20) |
| 2 | Change format name | Input | Char(8) |
| 3 | Subsystem entry identifier | Input | Char(*) |
| 4 | Change information | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Change Subsystem Entry (QWDCSBSE) API changes a subsystem entry in the specified subsystem description.
Authorities and Locks
- Job Description Authority
- *USE
- Job Description Library Authority
- *EXECUTE
- Subsystem Description Authority
- *OBJMGT, *USE
- Subsystem Description Library Authority
- *EXECUTE
- User Profile Authority
- *USE
Required Parameter Group
- Qualified subsystem name
- INPUT; CHAR(20)
The subsystem description that contains the subsystem entry being changed. 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
- Change format name
- INPUT; CHAR(8)
The format of the subsystem entry to change. You can use the following format:
SBSE0500 Prestart job entry. For details, see SBSE0500 Format (Prestart Job Entry).
- Subsystem entry identifier
- INPUT; CHAR(*)
The subsystem entry that is to be changed. The identifier is specific to the entry type. For prestart job entries, see SBSE0500 Format (Prestart Job Entry) for details.
- Change information
- INPUT; CHAR(*)
The information for the subsystem entry that you want to change. The information must be in the following format:
- Number of variable length records
- BINARY(4)
The total number of all of the variable length records.
- Variable length records
- The attributes of the subsystem entry that are to be changed. Refer to Format for Variable Length Record for more information.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format for Variable Length Record
The following table shows the layout of the variable length record. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of variable length record |
| 4 | 4 | BINARY(4) | Attribute key |
| 8 | 8 | BINARY(4) | Length of data |
| 12 | C | CHAR(*) | Data |
If the length of the data is longer than the key field's data length, the data is truncated at the right. No message is issued.
If the length of the data is shorter than the key field's data length and the key contains binary data, an error message is issued. If the key does not contain binary data, the field is padded with blanks.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.
Field Descriptions
Attribute key. The attribute to be set. For prestart job entries, see SBSE0500 Format (Prestart Job Entry) for details.
Data. The value to which a specific attribute is to be set.
Length of data. The length of the attribute value.
Length of variable length record. The length of the record including this field.
SBSE0500 Format (Prestart Job Entry)
This format changes a prestart job entry in the specified subsystem description. The associated subsystem may be active when the prestart job entry is changed. Changes made to the entry when the subsystem is active are reflected over time. Prestart jobs that are created after the API is issued use the new job-related values.
Subsystem Entry Identifier for SBSE0500 Format
- Qualified program name
- CHAR(20)
The qualified name of the program that identifies the prestart job entry being changed. The first 10 characters contain the program 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
Attribute Keys for SBSE0500 Format
The following table shows the valid attribute keys for the attribute key field of the variable length record. For a detailed description of each field, see Field Descriptions of Attribute Keys for SBSE0500 Format.
| Key | Type | Field |
|---|---|---|
| 1 | CHAR(10) | User profile name |
| 2 | CHAR(1) | Start jobs |
| 3 | BINARY(4) | Initial number of jobs |
| 4 | BINARY(4) | Threshold |
| 5 | BINARY(4) | Additional number of jobs |
| 6 | BINARY(4) | Maximum number of jobs |
| 7 | CHAR(10) | Job name |
| 8 | CHAR(20) | Job description name |
| 9 | BINARY(4) | Maximum number of uses |
| 10 | CHAR(1) | Wait for job |
| 11 | BINARY(4) | Pool identifier |
| 12 | CHAR(20) | Class 1 name |
| 13 | BINARY(4) | Class 1 number of jobs |
| 14 | CHAR(20) | Class 2 name |
| 15 | BINARY(4) | Class 2 number of jobs |
| 16 | CHAR(20) | Thread resources affinity |
| 18 | CHAR(10) | Resources affinity group |
Field Descriptions of Attribute Keys for SBSE0500 Format
Additional number of jobs. The additional number of prestart jobs that are started when the number of prestart jobs drops below the threshold value. The value of this parameter must be less than the value of the maximum number of jobs. Valid values range from 0-999.
Class 1 name. The name of a class under which the prestart jobs run. Two classes can be specified for a prestart job entry, class 1 name and class 2 name. Each class defines the number of jobs that run under that class. See class 1 number of jobs and class 2 number of jobs.
Jobs start under the first class specified until the number of jobs specified for the first class is reached. After the allowed number of jobs specified for the first class is reached, jobs are started under the second class.
The possible values are:
| *SBSD | The class that has the same name as the subsystem description specified in the qualified subsystem name is used for prestart jobs. | ||||
| Qualified class name | The name of the class used for prestart jobs. The
first 10 characters contain the class name, and the second 10 characters
contain the library name. You can use these special values for the library
name:
If the class does not exist when the entry is added, a library qualifier must be specified because the qualified class name is retained in the subsystem description. |
Class 1 number of jobs. The maximum number of jobs to run that use the first class. If you specified the maximum number of jobs key to be changed, the value for the number of jobs specified for this key might need to be changed. If -3 or -4 is specified, the system recalculates the value for the number of jobs to use the specified class. The possible values are:
| -3 | *CALC: 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 divided by two, and the second class is the value of the maximum number of jobs minus the value 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 | *MAXJOBS: All prestart jobs use the specified class. |
| number of jobs | The number of jobs that use this class. The sum of the values specified for class 1 and class 2 number of jobs must equal the value of the maximum number of jobs. If you specify one of the class number of job keys, you may also need to specify the maximum number of jobs keys. |
Class 2 name. The name of a class under which the prestart jobs run. Two classes can be specified for a prestart job entry, class 1 name and class 2 name. Each class defines the number of jobs that run under that class. See class 1 number of jobs and class 2 number of jobs.
Jobs start under the first class specified until the number of jobs specified for the first class is reached. After the allowed number of jobs specified for the first class is reached, jobs are started under the second class.
The possible values are:
| *NONE | This value indicates that only one class is used. | ||||
| *SBSD | The class that has the same name as the subsystem description specified in the qualified subsystem name is used for prestart jobs. | ||||
| Qualified class name | The name of the class being used for prestart
jobs. The first 10 characters contain the class name, and the second 10
characters contain the library name. You can use these special values for the
library name:
If the class does not exist when the entry is added, a library qualifier must be specified because the qualified class name is retained in the subsystem description. |
Class 2 number of jobs. The maximum number of jobs that use the second class. The possible values are:
| -3 | *CALC: 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 divided by two, and the second class is the value of the maximum number of jobs minus the value 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 the maximum number of jobs and the specific number of jobs for the -3 designation. |
| -4 | *MAXJOBS: All prestart jobs use the specified class. |
| number of jobs | The number of jobs that use this class. The sum of the values specified for class 1 and class 2 number of jobs must equal the value of the maximum number of jobs. If you specify one of the class number of job keys, you may also need to specify the maximum number of jobs keys. |
Initial number of jobs. The initial number of prestart jobs that are started when the subsystem specified in the qualfified subsystem name is started. The value of this key must be less than or equal to the value of the maximum number of jobs. The value of this key must be greater than or equal to the value of the threshold. Valid values range from 1-9999.
Job description name. The name of the job description being used for the prestart job. If the job description does not exist when the entry is changed, a library qualifier must be specified because the qualified job description name is retained in the subsystem description.
| *USRPRF | The job description name specified in the user profile for the prestart job entry is used. | ||||
| *SBSD | The job description that has the same name as the subsystem description for this prestart job entry is used. | ||||
| Qualified job description name | The name of the job description being used for
this prestart job. The first 10 characters contain the job description name,
and the second 10 characters contain the library name. You can use these
special values for the library name:
|
Job name. The name of the prestart job that is started.
| *PGM | The job name is the same name as the qualified program name specified in the subsystem entry identifier. |
| job-name | The name of the prestart job. |
Maximum number of jobs. The maximum number of prestart jobs that can be active at the same time for this prestart job entry. The value of this key must be greater than or equal to the value of the initial number of jobs. The value of this key must be greater than the value of the additional number of jobs. If the value specified for this key is changed, the value specified for one or both of the class number of job keys might also need to be changed. The possible values follow:
| -1 | *NOMAX: There is no maximum number of jobs that can be active at the same time. |
| maximum-jobs | The maximum number of prestart jobs that can be active at the same time. Valid values range from 1-9999. |
Maximum number of uses. The maximum number of that can be handled by each prestart job before the subsystem ends the job in a controlled manner. Jobs are ended in a controlled manner by issuing an ENDJOB command with a value of *CNTRLD on the OPTION parameter.
| -1 | *NOMAX: There is no maximum number of that a prestart job can handle before it is ended. If -1 is specified, the prestart jobs may end abnormally because the job has exceeded the allowed maximum job log size, the maximum number of spooled files, the maximum processor unit time, or the maximum temporary storage space required. |
| maximum-uses | The maximum number of that a prestart job can handle before it is ended. Valid values range from 1 through 1000. |
Pool identifier. The subsystem pool identifier under which the prestart jobs are run. Valid values range from 1 through 10.
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 values allowed 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. |
Start jobs. Whether prestart jobs are started when the subsystem is started. The possible values are:
| 0 | The prestart jobs are not started at the time the subsystem is started. The Start Prestart Jobs (STRPJ) command must be used to start these prestart jobs. |
| 1 | The prestart jobs are started when the subsystem is started. |
Thread resources affinity. 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 values allowed for the first 10 characters are:
| *SYSVAL | The thread resources affinity group and level will be retrieved from the QTHDRSCAFN system value 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. |
The last 10 characters of this field specifies the degree to which the system tries to maintain the affinity between threads and system resources. If *SYSVAL is specified in the first 10 characters, the last 10 characters must contain blanks. If *SYSVAL is not specified, the values allowed 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. |
Threshold. The number at which additional prestart jobs are started. When the pool of available prestart jobs (jobs available to service is reduced below this number, more jobs (specified by the additional number of jobs value) are started and added to the available pool. The value of this key must be less than or equal to the value of the initial number of jobs. Valid values range from 1-9999.
User profile name. The user profile under which the prestart job is initiated. In addition, the current user profile of the prestart job is set to this user whenever the job waits for a request to handle.
Note: When a prestart job is given a request to handle, the current user profile of the job is updated. Refer to the Work management topic collection for information on how this profile is determined. This change in current user profile is for authority checking only. None of the other attributes of the user profile, such as the current library (CURLIB) or the initial program to call (INLPGM), are given to the prestart job.
Wait for job. Whether program start requests wait for a prestart job to become available or are rejected if a prestart job is not immediately available when the program start request is received. Refer to the manual for the communications type being used to determine the timing considerations for program start requests. The possible values follow:
| 0 | Program start requests are rejected if a prestart job is not immediately available when the program start request is received. |
| 1 | Program start requests wait until a prestart job is available, or a prestart job is started to service the request. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1619 E | Subsystem description &1 in library &2 damaged. |
| CPF1697 E | Subsystem description &1 not changed. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V4R3