Define name and attributes for new job variable
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 CREATE-JV command generates the catalog entry for a JV whose value is undefined until the first change. The user defines the name of the JV and the following protection attributes:
read-only or read/write access (ACCESS operand); part of standard access control
access by foreign user IDs (USER-ACCESS operand); part of standard access control
explicit assignment of access rights (BASIC-ACL operand); extended access control
protection by guards (GUARDS operand)
additional protection via passwords (READ- and WRITE-PASSWORD operands)
HSMS management class (MANAGEMENT-CLASS operand)
The protection attribute “retention period” is set implicitly. It can only be assigned via the MODIFY-JV-ATTRIBUTES command (RETENTION-PERIOD operand). By default, no retention period is defined for newly created JVs, i.e. the output field EXPIR-DATE in the catalog entry contains the creation date (output field CRE-DATE). Currently, the output field EXPIR-TIME is always set to the value 00:00:00. For the creation time (output field CRE-TIME), the actual time of creation is entered.
For temporary JVs, only the preset values are allowed, i.e. they are not shareable, can always be overwritten and cannot be protected by passwords. The protection function BASIC-ACL is likewise not supported. Since only the creating job can access temporary JVs up to LOGOFF processing, no protection is required against foreign access.
When creating permanent JVs, the user cannot exceed the maximum permitted number specified in the user entry for the relevant pubset. If the number of permanent JVs is the same as the maximum permitted number, any further CREATE-JV commands for creating a permanent JV are rejected (see the JOBVARIABLES and JV-NUMBER-LIMIT output fields of the SHOW-USER-ATTRIBUTES command).
Privileged functions
By default, systems support (TSOS privilege) is a co-owner of all job variables (and can, therefore, create job variables under all user logons). When SECOS is used, this co-ownership can be restricted for permanent job variables.
Format
CREATE-JV | Alias: CRJV | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
JV-NAME = <filename 1..54 without-gen-vers>
Name of the job variable JV to be created.
Nonprivileged users can create job variables under their own user ID only. The name of a temporary JV begins with the character (# or @) specified in the TEMPFILE system parameter. The internal name is always output by the system (e.g. SHOW-JV-ATTRIBUTES, system messages).
PROTECTION = *STD / *PARAMETERS(...)
Protection attributes of the JV.
PROTECTION = *STD
The protection attributes listed below are assigned the values supplied by default protection.
If default protection is not active, the system default values for the operands of the *PARAMETERS structure are set.
PROTECTION-ATTR= | *STD | *BY-DEF-PROT-OR-STD | |
|---|---|---|---|
Default protection not active | Default protection active | ||
(System standard values) | |||
ACCESS | WRITE | values from default protection | |
USER-ACCESS | OWNER-ONLY | ||
BASIC-ACL | NONE | ||
PASSWORD | NONE | ||
READ-/WRITE-PASSWORD | NONE | ||
PROTECTION = *PARAMETERS(...)
The protection attributes of the JV are set as follows. If the default value *NONE or *NO is specified for an attribute, the corresponding protection function is not activated. The protection attribute ACCESS is implicitly set to WRITE (explicitly only with MODIFY-JV-ATTRIBUTES).
For temporary JVs, only the default values are permitted. They are not shareable, can always be overwritten and cannot be protected by passwords. The protection functions basic ACL and guards are likewise not supported. Since only the creating job can access temporary JVs up to LOGOFF processing, 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 following table shows the method used for access control, the protection attributes, and the job variable protection 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 | GUARDS and SECOS | 2 |
All other protection attributes of a JV (e.g. passwords) are evaluated independently of the protection level.
PROTECTION-ATTR = *BY-DEF-PROT-OR-STD / *STD
Specifies from where the protection attributes with the value *BY-PROTECTION-ATTR are to be obtained.
For the assignments, see table "Effects of PROTECTION-ATTR on protection attributes in the case of CREATE-JV".
PROTECTION-ATTR = *BY-DEF-PROT-OR-STD
The values supplied by default protection are entered for the operands with *BY-PROTECTION-ATTR. If default protection is not active, system default values will be assigned to the relevant operands.
PROTECTION-ATTR = *STD
System default values are set for operands with *BY-PROTECTION-ATTR.
ACCESS = *BY-PROTECTION-ATTR / *WRITE / *READ
Specifies the type of accesses allowed when only standard access control is active (i.e. when there is no BASIC-ACL entry and no protection with GUARDS).
ACCESS = *BY-PROTECTION-ATTR
Standard access control is independent of the value of the PROTECTION-ATTR operand.
ACCESS = *WRITE
Standard access control allows both read and write access.
ACCESS = *READ
Standard access control allows read access only.
USER-ACCESS = *BY-PROTECTION-ATTR / *OWNER-ONLY / *ALL-USERS
Specifies whether the accesses allowed with the ACCESS operand are also available to other user IDs when only standard access control is active (i.e. when there is no BASIC-ACL entry and no protection with GUARDS).
USER-ACCESS = *BY-PROTECTION-ATTR
Access is independent of the value of the PROTECTION-ATTR operand.
USER-ACCESS = *OWNER-ONLY
Only the owner (user ID under which the JV is cataloged) and the system administration have access.
USER-ACCESS = *ALL-USERS
All user IDs have access rights.
BASIC-ACL = *BY-PROTECTION-ATTR / *NONE / STD / *PARAMETERS(...)
Specifies whether a BASIC-ACL entry is to be generated for the JV and whether access control is consequently to be performed through that entry.
BASIC-ACL = *BY-PROTECTION-ATTR
Access control via BASIC-ACL is independent of the value of the PROTECTION-ATTR operand.
BASIC-ACL = *NONE
BASIC-ACL is not activated for the JV. Access control (standard access control) is effected in accordance with the protection attributes USER-ACCESS and ACCESS (see output fields USER-ACC and ACCESS of the SHOW-JV-ATTRIBUTES command).
BASIC-ACL = *STD
A BASIC-ACL entry with the following values is created for the JV:OWNER = *PARAMETERS( READ = *YES, WRITE = *YES),GROUP = *NO-ACCESS and OTHERS = *NO-ACCESS
BASIC-ACL = PARAMETERS(...)
A BASIC-ACL entry is created for the JV and access control is then effected via the basic access control list (BACL).
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.
OWNER = *NO-ACCESS / *PARAMETERS(...)
Specifies which access rights are to be set for the owner. NO-ACCESS is the default value, i.e. the owner has neither read nor write authorization.
OWNER = *PARAMETERS(...)
The owner’s access rights are entered as specified:
READ = *NO / *YES
Specifies whether read authorization is set.
WRITE = *NO / *YES
Specifies whether write authorization is specified.
Write authorization does not imply read authorization.
GROUP = *NO-ACCESS / *PARAMETERS(...)
Specifies which access rights are to be set for all user IDs from the group of the owner.NO-ACCESS is the default value, i.e. the user class GROUP has neither read nor write authorization.
GROUP = *PARAMETERS(...)
Access rights are to be set as specified:
READ = *NO / *YES
Specifies whether read authorization is set.
WRITE = *NO / *YESSpecifies whether write authorization is specified.
Write authorization does not imply read authorization.
OTHERS = *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.
*NO-ACCESS is the default value, i.e. the user class OTHERS has neither read nor write authorization.
OTHERS = *PARAMETERS(...)
Access rights are to be set as specified:
READ = *NO / *YES
Specifies whether read authorization is set.
WRITE = *NO / *YES
Specifies whether write authorization is specified.
GUARDS = *BY-PROTECTION-ATTR / *NONE / *PARAMETERS(...)
Specifies whether access control is to be performed for the JV using GUARDS.
GUARDS = *BY-PROTECTION-ATTR
Access control using GUARDS is independent of the value of the PROTECTION-ATTR operand.
GUARDS = *NONE
Access to the JV is not to be controlled via GUARDS.
GUARDS = *PARAMETERS(...)
Access to the JV is to be controlled via GUARDS.
Access to the job variable 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, time period, 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. A check by GUARDS takes place only when JV access occurs:
If a defined guard is not accessible, the mode of access protected by it is not permitted. No access at all is possible if the GUARDS subsystem is not available at the time of access.
READ = *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 = *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.
READ-PASSWORD = *BY-PROTECTION-ATTR / *NONE / *SECRET / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647>
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 = *BY-PROTECTION-ATTR
Allocation of a read password is independent of the value of the PROTECTION-ATTR operand.
WRITE-PASSWORD = *BY-PROTECTION-ATTR / *NONE / *SECRET / <c-string 1..4> / <x-string 1..8> / <integer -2147483648..2147483647>
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 = *BY-PROTECTION-ATTR
Allocation of a write password is independent of the value of the PROTECTION-ATTR operand.
MANAGEMENT-CLASS = *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” 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
SUPPRESS-ERRORS = *NONE / *JV-EXISTING
Specifies whether there is an error if the specified JV exists.
SUPPRESS-ERRORS = *NONE
If the specified JV exists, the command is rejected with an error. The error triggers the spinoff mechanism resp. the SDF-P error handling.
SUPPRESS-ERRORS = *JV-EXISTING
If the specified JV already exists, the command has no effect on the JV. There is no error (error JVS0444 is suppressed).
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed | |
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 |
Examples
/create-jv jv=jv.perm.error,prot=*par(user-access=*all-users,write-pass=c'fehl')
/show-jv-attr jv=jv.perm.error,inf=*all-attr
%0000000 :LEO:$USER1.JV.PERM.ERROR % USER-ACC = ALL-USERS ACCESS = WRITE % CRE-DATE = 2012-03-15 EXPIR-DATE = 2012-03-15 % CRE-TIME = 09:09:00 EXPIR-TIME = 00:00:00 % READ-PASS = NONE % WRITE-PASS = YES %SUM 000001 JV'S; JV-VALUE = 00000000 BYTES
The job variable JV.PERM.ERROR is created, i.e. its name is entered in the catalog. The job variable is defined as shareable and protected by a write password.
/create-jv jv=jv.perm.error.read,
prot=(basic-acl=(owner=(read=y,write=y),group=(read=y),others=(read=y)))
/show-jv-attr jv=jv.perm.error.read,inf=*all-attr
%0000000 :LEO:$TSOS.JV.PERM.ERROR.READ % USER-ACC = OWNER-ONLY ACCESS = WRITE % OWNER = R W GROUP = R - OTHERS = R - % CRE-DATE = 2012-01-19 EXPIR-DATE = 2012-01-19 % CRE-TIME = 18:18:29 EXPIR-TIME = 00:00:00 % READ-PASS = NONE % WRITE-PASS = NONE %SUM 000001 JV'S; JV-VALUE = 00000000 BYTES
The job variable JV.PERM.ERROR.READ is created. It is not shareable, but read authorization is granted to other users via BASIC-ACL. The owner has both read and write access.
/create-jv jv=#jv.temp.work
/show-jv-attr jv=#jv.temp.work,inf=*all-attr
%0000000 :LEO:$TSOS.S.123.4HM7.JV.TEMP.WORK % USER-ACC = OWNER-ONLY ACCESS = WRITE % CRE-DATE = 2012-01-19 EXPIR-DATE = 2012-01-19 % CRE-TIME = 18:22:44 EXPIR-TIME = 00:00:00 % READ-PASS = NONE % WRITE-PASS = NONE %SUM 000001 JV'S; JV-VALUE = 00000000 BYTES
The job variable #JV.TEMP.WORK is created temporarily. The protection attributes are set to their default values (different values cannot be specified). Only the creating job has access.