Modify job variable attributes
Component: | JV |
Functional area: | Job variables |
Domain: | JOB-VARIABLES |
Privileges: | STD-PROCESSING |
Routing code: | $ (with NBCONOPI=N) or J (with NBCONOPI=Y) |
This function is only available to the user if the chargeable software product JV has been loaded as a subsystem.
Function
The MODIFY-JV-ATTRIBUTES command modifies the catalog entry of a JV. The user can change the name of the JV (NEW-NAME), as well as redefine the protection attributes of a permanent JV:
read/write access to the JV (ACCESS), component of standard access control,
access by other user IDs (USER-ACCESS), part of standard access control,
access rights which are assigned with the protection attribute BASIC-ACL, extended access control,
protection by guards (GUARDS operand)
passwords for the JV (WRITE-PASSWORD/READ-PASSWORD),
retention period for the JV (RETENTION-PERIOD),
release of the lock imposed on a monitoring JV (MONJV-PROTECTION).
HSMS management class (MANAGEMENT-CLASS operand)
The catalog entry of a JV which is monitoring an executing job can only be modified if the lock is released. The catalog entry of a JV which is used in CJC commands and macros can likewise not be modified (information can be obtained via the SHOW-CJC-STATUS command).
Privileged functions
By default, systems support (TSOS privilege) is a co-owner of all the job variables (and can therefore also modify their catalog entries). When SECOS is used, this co-ownership can be restricted for permanent job variables.
Format
MODIFY-JV-ATTRIBUTES | Alias: MDJVA | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
JV-NAME = <filename 1..54 without-gen-vers>
Existing name of the JV.
Nonprivileged users may specify their own user ID only.
NEW-NAME = *SAME / <filename 1..54 without-gen-vers>
New name for the JV. Default value *SAME, i.e. no new name for the JV.
A new name can be specified explicitly with catalog ID and user ID, but any attempt to change the previous catalog or user IDs is rejected as an error.
When renaming a permanent JV to a temporary JV, the protection attributes must be left at their default values (see the CREATE-JV command) or be set explicitly to the default values in the PROTECTION operand. Default settings for the protection attributes: ACCESS=*WRITE, USER-ACCESS=*OWNER-ONLY, BASIC-ACL=*NONE, WRITE-PASSWORD=*NONE, READ-PASSWORD=*NONE, RETENTION-PERIOD=0
PROTECTION =
Protection attributes of the JV.
PROTECTION = *UNCHANGED
The protection attributes remain unchanged.
A change in the protection attributes is not permissible for temporary JVs.
PROTECTION = *PARAMETERS(...)
Specifies which protection attributes are to be changed.
*UNCHANGED is the default value for all protection attributes: A protection attribute is only changed if the desired value is explicitly specified.
For temporary JVs, only the default values are permitted. Since only the creating job can access temporary JVs, no protection is required against foreign access.
If more than one access control mechanism is specified for a JV, the strongest mechanism activated applies. The table below lists the types of access control that exist, the corresponding protection attributes and their hierarchy (protection levels):
Access control method | Protection attribute | Prot. level |
|---|---|---|
Standard access control | ACCESS and USER-ACCESS | 0 |
Basic access control list | BASIC-ACL | 1 |
Access control via guards | PASSWORD | 2 |
All other protection attributes of the file (e.g. passwords) are evaluated independently, without regard to the implemented protection level.
ACCESS = *UNCHANGED / *WRITE / *READ
Write access (implicit read access) or only read access to the JV.
USER-ACCESS = *UNCHANGED / *OWNER-ONLY / *ALL-USERS
Specifies whether external user IDs may access the JV.
BASIC-ACL = *UNCHANGED / *NONE / *PREVIOUS / *PARAMETERS(...)
Specifies whether a BACL is to be activated, changed or turned off for the job variable.
BASIC-ACL = *NONE
An activated basic ACL is turned off for the JV. The access control is thereby effected in accordance with the values of USER-ACCESS and ACCESS (standard access control).
BASIC-ACL = *PREVIOUS
An already existing BASIC-ACL entry is not changed.
If the JV is not protected by a basic ACL, a BASIC-ACL entry is created. Thereby the values of the standard access control (ACCESS and USER-ACCESS) are taken over into the BASIC-ACL entry in accordance with the following table:
Standard access control | BASIC-ACL protection | ||||||
|---|---|---|---|---|---|---|---|
USER-ACCESS | ACCESS | OWNER | GROUP | OTHERS | |||
R | W | R | W | R | W | ||
OWNER-ONLY | WRITE | Y | Y | N | N | N | N |
OWNER-ONLY | READ | Y | N | N | N | N | N |
ALL-USERS | WRITE | Y | Y | Y | Y | Y | Y |
ALL-USERS | READ | Y | N | Y | N | Y | N |
BASIC-ACL = *PARAMETERS(...)
The BACL is activated for the job variable or individual access rights of an existing BACL are changed. The read and write access rights can be explicitly set or denied for each user class. User classes are:
OWNER, i.e. user ID of the owner and systems support
GROUP, i.e. all user IDs which belong to the group of the owner (except the owner and systems support). Definition of user groups is possible only when the software product SECOS is used. With regard to the possible use of SECOS, the same rights should be allocated for GROUP as for OTHERS.
OTHERS, i.e. all user IDs which do not belong to the group of the owner.
BASIC-ACL is activated if the value *NO-ACCESS or *PARAMETERS is specified for at least one authorized user. In this case, the corresponding access authorization is set to “no access right” for those authorized users for whom the value *UNCHANGED was not changed (corresponds to specifying *NO-ACCESS).
OWNER = *UNCHANGED / *NO-ACCESS / *PARAMETERS(...)
Specifies which access rights are to be set for the owner. For a newly activated BASIC-ACL, *UNCHANGED is treated in the same way as *NO-ACCESS. With *NO-ACCESS, the owner has no access rights.
OWNER = *PARAMETERS(...)
The owner’s access rights are entered as specified:
READ = *UNCHANGED / *NO / *YES
Specifies whether read authorization is set.
*UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
WRITE = *UNCHANGED / *NO / *YES
Specifies whether write authorization is specified.
Write authorization does not imply read authorization. *UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
GROUP = *UNCHANGED / *NO-ACCESS / *PARAMETERS(...)
Specifies which access rights are to be set for all user IDs from the group of the owner. Without SECOS, that is all user IDs which do not belong to a group other than that of the owner. For a newly activated BASIC-ACL, *UNCHANGED is treated in the same way as *NO-ACCESS. With *NO-ACCESS, GROUP has no access rights.
GROUP = *PARAMETERS(...)
Access rights are to be set as specified:
READ = *UNCHANGED / *NO / *YES
Specifies whether read authorization is set.
*UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
WRITE = *UNCHANGED / *NO / *YES
Specifies whether write authorization is specified.
Write authorization does not imply read authorization. *UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
OTHERS = *UNCHANGED / *NO-ACCESS / *PARAMETERS(...)
Specifies which access rights are to be set for user IDs which do not belong to the group of the owner. If SECOS is not used, access rights should be set as for
GROUP with regard to an analysis for future use of SECOS. For a newly activated BASIC-ACL, *UNCHANGED is treated in the same way as *NO-ACCESS. With *NO-ACCESS, OTHERS has no access rights.
OTHERS = *PARAMETERS(...)
Access rights are to be set as specified:
READ = *UNCHANGED / *NO / *YES
Specifies whether read authorization is set.
*UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
WRITE = *UNCHANGED / *NO / *YES
Specifies whether write authorization is specified.
Write authorization does not imply read authorization. *UNCHANGED is the default value, i.e. no read authorization (corresponds to *NO) when BASIC-ACL is reactivated.
GUARDS = *UNCHANGED / *NONE / *PARAMETERS(...)
Specifies whether access control via GUARDS is to be activated or modified for the JV.
GUARDS = *NONE
Access to the JV is not (is no longer) to be controlled via GUARDS.
GUARDS = *PARAMETERS(...)
Any existing access control via GUARDS for the JV is to be modified as specified. If no protection by guards has been defined for the JV, access control via GUARDS is activated only if a value other than *UNCHANGED is specified for at least one of the READ or WRITE operands.
Access to the file is controlled via a guard, i.e. a specific object identifying all the conditions subject to which access will be granted: such as date, time and user ID. The GUARDS function unit of the chargeable software product SECOS (see the “SECOS” manual [35]) must be installed in order to create and maintain a guard. Each guard is uniquely identified by its name. Guard names resemble JV names: they are made up of two parts, the user ID (optional) and the name part (up to 8 characters). If no user ID is specified explicitly, the user’s own ID is added implicitly. Each access mode can be controlled by a separate guard. If no guard is assigned for an access mode (*NONE), access control will refuse any corresponding access (e.g. WRITE=*NONE prevents all write access). Specifying GUARDS=*PARAMETERS defines access control via GUARDS with all access modes being set to the default value *NONE, i.e. neither read access to the JV nor write or execute access is allowed.
The GUARDS subsystem is not required in order to define access control via GUARDS. The appropriate checks by GUARDS are not performed until the JV is actually accessed: If a guard has been defined but is not available, all access of the type controlled by that guard is prohibited. No access at all is possible if the GUARDS subsystem is not available at the time of access.
READ = *UNCHANGED / *NONE / <filename 1..18 without-cat-gen-vers>
Name of a guard controlling read access (up to 8 characters if no user ID is specified). The default value is *NONE, i.e. no read access is granted.
WRITE = *UNCHANGED / *NONE / <filename 1..18 without-cat-gen-vers>
Name of a guard controlling write access (up to 8 characters if no user ID is specified). The default value is *NONE, i.e. no write access is granted.
WRITE-PASSWORD = *UNCHANGED / *NONE / <c-string 1..4> / <x-string 1..8> /
<integer -2147483648..2147483647> / *SECRET
Write or read password for the JV to be modified. The WRITE-PASSWORD operand has the following special characteristics:
The input field is automatically blanked out in the guided dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^, SDF provides a blanked out input field for inputting the password .
The password entered is not logged.
WRITE-PASSWORD = *NONE
No password for the JV. Any write password that may have been defined is removed.
READ-PASSWORD = *UNCHANGED / *NONE / <c-string 1..4> / <x-string 1..8> /
<integer -2147483648..2147483647> / *SECRET
Password for protection against unauthorized reading. The READ-PASSWORD operand has the following special characteristics:
The input field is automatically blanked out in the guided dialog.
In unguided dialog and foreground procedures, the entry *SECRET or ^, SDF provides a blanked out input field for inputting the password .
The password entered is not logged.
READ-PASSWORD = *NONE
No password for the JV. Any read password that may have been defined is removed.
RETENTION-PERIOD = *UNCHANGED / <integer 0..32767 days >
Retention period in days. In the catalog entry, the date in output field EXPIR-DATE is set to a value computed from the current date and the specified number of days. The JV is protected against being modified or deleted up to this date. The time for the defined expiration date is currently entered as 00:00:00 hours in the catalog. Specifying RETENTION-PERIOD=0 causes the expiration date to be set to the current date, thereby canceling any retention period set.
MONJV-PROTECTION = *UNCHANGED / *NO
Specifies whether the lock on the specified monitoring JV is to be retained. The system automatically locks monitoring job variables against write access until the job being monitored is ended.
MONJV-PROTECTION = *NO
Any lock present is to be removed. The user should ensure that the monitored job has already been removed from the job queue (SHOW-JOB-STATUS).
MANAGEMENT-CLASS = *UNCHANGED / *NONE / <composed-name 1..8>
Only for job variables on SM pubsets Specifies whether the HSMS functions JV backup and (long-term) archival are to be controlled via a management class defined via HSMS. See the “HSMS, Volume 1” manual [18] for further details. Assignment of a management class is rejected in the following cases:
the JV is to be created on an SF pubset
the specified management class has not been defined for the SM pubset
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed | |
1 | 0 | CMD0001 | No action necessary |
2 | 0 | CMD0001 | Command executed with a warning |
1 | CMD0202 | Syntax error | |
32 | CMD0221 | System error | |
64 | JVS04E0 | Command not executable in the call environment; if possible, remove cause of error (see SYSOUT message JVS04xx) | |
130 | JVS04E1 | Command cannot be executed at this time; for cause see SYSOUT message JVS04xx | |
130 | CMD2282 | Subsystem JV not available for indefinite time |
Example
/create-jv jv=test/show-jv-attr jv=test,inf=*all-attr
%0000000 :LEO:$USER1.TEST % USER-ACC = OWNER-ONLY ACCESS = WRITE % CRE-DATE = 2012-01-09 EXPIR-DATE = 2012-01-09 % CRE-TIME = 16:09:36 EXPIR-TIME = 00:00:00 % READ-PASS = NONE % WRITE-PASS = NONE %SUM 000001 JV'S; JV-VALUE = 00000000 BYTES
/mod-jv-attr jv=test,new-name=probe ——————————————————————————————————— (1)/mod-jv-attr jv=probe,prot=(user-access=*all-users,write-pass=c'fehl', ret-per=10) ————————————————————————————————————————————— (2) /show-jv-attr jv=probe,inf=*all-attr
%0000000 :LEO:$USER1.PROBE % USER-ACC = ALL-USERS ACCESS = WRITE % CRE-DATE = 2012-01-09 EXPIR-DATE = 2012-01-19 % CRE-TIME = 16:09:36 EXPIR-TIME = 00:00:00 % READ-PASS = NONE % WRITE-PASS = YES %SUM 000001 JV'S; JV-VALUE = 00000000 BYTES
/add-pass pass=c'fehl' ———————————————————————————————————————————————— (3)/del-jv jv=probe —————————————————————————————————————————————————————— (4)
% JVS04A3 ERROR WHEN DELETING JOB VARIABLE ':LEO:$USER1.PROBE' % JVS04B6 EXPIRATION DATE FOR JOB VARIABLE NOT YET REACHED. COMMAND REJECTED /
(1) | The job variable TEST is renamed PROBE. |
(2) | The JV PROBE is made accessible to all users and receives a write password. It also cannot be modified or deleted for a period of 10 days. |
(3) | The write password is added to the password table. |
(4) | Because of the retention period of 10 days, the DELETE-JV command is rejected. |