General
Domain: | Job variables |
Macro type: | Type S (standard form/C/D/E/L form) see section “The MF operand” |
In the C and D forms of the macro, a prefix (PREFIX = pre, where pre is 1..3 letters) can be specified (see section “The PREFIX operand”). | |
Default value: | PREFIX=IDJ |
Macro description
The CATJV macro creates or updates the catalog entry of a job variable.
Explicitly deactivating the default protection with CATJV ..., PROTECT=STD is only supported when the operand VERSION=4 is also specified at the same time.
Using macro versions < 4 can lead to problems in conjunction with default protection: if a JV receives the protection attribute SHARE=YES or ACCESS=READ or passwords via default protection, then the non-privileged user can set the protection attribute to
SHARE=NO or ACCESS=WRITE or RDPASS=NONE or WRPASS=NONE. These specifications are not evaluated, however, as the default protection settings have a higher priority.
Macro call format and operand description
Operation | Operands |
|
( [{ READ={YES / NO} | R={Y / N} }] [,{ WRITE={YES / NO} | W={Y / N} }] ) } ]
( [{ READ={ YES / NO } | R={ Y / N } }] [,{ WRITE={ YES / NO } | W={ Y / N } }] ) } ]
( [{ READ={YES / NO} | R={Y / N} }] [,{ WRITE={YES / NO} | W={Y / N} }] ) } ]
( [READ={*NONE / readguard}] [,WRITE={*NONE / writeguard}] )
|
jvname1
Fully qualified path name under which the permanent or temporary job variable is cataloged. Only systems support may specify a user ID other than their own.
jvname2
Specifies a new name for job variable jvname1. Up to versions < 2, user ID and catalog ID must not be specified as this could indicate a change of owner or catalog. From version = 2 on, a fully qualified path name can be specified, but user ID and catalog ID must match the IDs specified in jvname1.
This operand is effective only in combination with STATE=UPDATE.
STATE=
Specifies that a catalog entry is to be created for a job variable which does not yet exist, or that an existing catalog entry is to be updated.
NEW
Is the default: a new catalog entry is to be created.
UPDATE
Specifies that an existing catalog entry is to be updated.
Note
In UPDATE mode, operands not specified are not set to their default value. In UPDATE mode, the corresponding value in the JV entry can only be modified by means of the ACCESS, SHARE, RDPASS, WRPASS and RETPD operands if it has been specified explicitly.
PROTECT=
Specifies where the protection attributes of the job variable to be cataloged and whose value is not specified explicitly are to be taken from. The specification of this operand is only permitted together with VERSION=4.
See the table “Default system values for job variable protection attributes” for the value assignments.
DEFAULT
The default setting: The protection attributes of the new job variable are cataloged with the values of the default protection function.
STD
The protection attributes of the new job variable are cataloged with the default system values.
ACCESS=
Specifies either read-only or read/write access to a job variable.
WRITE
Default value if STATE=NEW; read and write access to the job variable is permitted.
READ
Only read access to the job variable is permitted.
SHARE=
Specifies whether or not the job variable can be used by any other user ID.
NO
Default value if STATE=NEW; the job variable must not be used by any other user IDs.
YES
Specifies that the job variable may also be used by other user IDs.
OWNERAR=
Specifies the access rights of the owner of the job variable (and of systems support). Read and write authorization must be explicitly assigned in each case.
This operand not allowed in combination with VERSION=0.
NO-ACCESS
The owner is explicitly denied both read and write authorization.
This is equivalent to specifying (READ=NO,WRITE=NO).
(READ=...,WRITE=...)
Read and write authorization are assigned as specified explicitly (READ/WRITE=YES) or not assigned (READ/WRITE=NO).
GROUPAR=
Specifies the access rights for all user IDs from the same group as the owner (except for the owner and systems support). This operand not allowed in combination with VERSION=0.
The definition of user groups is only possible if the software product SECOS is used.
With a view to the possible use of SECOS, the same rights should be assigned to GROUP as to OTHERS.
NO-ACCESS
User IDs of the owner group are explicitly denied both read and write authorization. This is equivalent to specifying (READ=NO, WRITE=NO).
(READ=...,WRITE=...)
Read and write authorization are assigned as specified explicitly (READ/WRITE=YES) or not assigned (READ/WRITE=NO).
OTHERAR=
Specifies the access rights of other users who do not belong to the owner group.
This operand not allowed in combination with VERSION=0.
If SECOS is not used, the access rights should nonetheless be set in the same way as for the owner group (GROUP) with a view to future possible use of SECOS.
NO-ACCESS
User IDs that do not belong to the owner group are explicitly denied both read and write authorization. This is equivalent to specifying (READ=NO, WRITE=NO).
(READ=...,WRITE=...)
Read and write authorization are assigned as specified explicitly (READ/WRITE=YES) or not assigned (READ/WRITE=NO).
BASACL=
Specifies whether a basic ACL is to be deleted, activated, or newly created for the job variable.
This operand not allowed in combination with VERSION=0.
NONE
An activated basic ACL for the job variable is deleted. When a new job variable is created (STATE=NEW), NONE is the default value, meaning that no basic ACL is defined.Access control is then effected in accordance with the values ACCESS and SHARE (standard access control).
STD
When the job variable is newly created (STATE=NEW), a basic ACL is created in which read and write access are permitted for the user group OWNER, and the user groups GROUP and OTHERS have no access rights.
If the job variable entry is updated (STATE=UPDATE), the value STD is evaluated only if no basic ACL was active. In this case a basic ACL is activated in which the access rights are set in accordance with the standard access control in the job variable entry (SHARE and ACCESS):
| Standard access control | BASIC-ACL protection | ||||||
| SHARE | ACCESS | OWNER | GROUP | OTHERS | |||
| R | W | R | W | R | W | ||
| NO | WRITE | Y | Y | N | N | N | N |
| NO | READ | Y | N | N | N | N | N |
| YES | WRITE | Y | Y | Y | Y | Y | Y |
| YES | READ | Y | N | Y | N | Y | N |
Table 30: Standard access control/BASIC-ACL (CATJV macro)
GUARDS=
Specifies whether a guard is to be deleted, activated or created for the job variable.
Specification of this operand is permissible only in conjunction with VERSION=3 or higher.
NONE
A previously defined guard is cancelled. When a new job variable is created (STATE=NEW), NONE is the default value, meaning that no guard is defined.
(READ=...,WRITE=...)
Read and/or write access is controlled via the specified guard (READ/WRITE=readguard/writeguard) or is not permitted at all (READ/WRITE=*NONE).
The name of the guard may be up to 8 characters long if specified without user ID. No catalog ID may be specified.
MANCLAS=
This operand is only evaluated for SM pubsets.
Specifies whether the HSMS functions JV backup, archival and (long term) archival are to be controlled via a management class defined via HSMS. See the manual “HSMS” [ 12 ] for further details.
Specification of this operand is permissible only in conjunction with VERSION=3 or higher.
*NONE
The controlling of HMHS functions via a management class is terminated. When a job variable is renewed (STATE=NEW), NONE is the default value and means that no management class is defined.
manclas
Name of the management class defined with HSMS.
RDPASS=
Defines a read password for the job variable or cancels a previously defined read password.
NONE
Cancels a previously defined read password. When a new job variable is created (STATE=NEW), NONE is the default and means that no read password is defined.
password
Defines the read password that must be given in order to access the job variable. Length <= 4 bytes. It must be a C string, an X string or a decimal number.
C string: C'character constant'; max. 4 characters.
X string: X'hexadecimal constant'; max. 8 characters.
Decimal number: -2147483648 <= number <= 2147483647
A password in the form X'00000000' or '0' is ignored. When a job variable is protected only by a read password, this password must also be specified in order to modify the job variable.
WRPASS=
Defines a write password for the job variable or cancels a previously defined write password.
NONE
Cancels a previously defined write password. When a new job variable is created (STATE=NEW), NONE is the default and means that no write password is defined.
password
Defines the write password that must be given in order to have write access to the job variable. Length <= 4 bytes. It must be a C string, an X string or a decimal number (see the RDPASS operand).
RETPD=
Specifies the retention period for the job variable.
0
Default value if STATE=NEW; the retention period is zero days.
This means that the expiration date field of the job variable entry contains today's date. (see the IDJEEXD field in the DSECT of the STAJV macro, ).
days
Number of days that the job variable is to remain safe against modification even if the other protection attributes permit write access.
The expiration date in the job variable entry contains the date on which protection is removed. The expiration date is the current date plus the specified number of days.
This operand is ignored unless STATE=UPDATE is specified, i.e. the job variable must already be cataloged. The maximum value for RETPD is 32767 days.
MONJV=
Specifies whether the protection attributes of a monitoring job variable are to remain unchanged.
UNCHANGED
Is the default: the protection for a job-monitoring job variable is to remain unchanged.
NO
Cancels protection of the system area (bytes 1 through 128) for a monitoring job variable. This specification is only effective in combination with STATE=UPDATE. Prior to the call, care must be taken to ensure that the monitored job has actually been removed from the queue (SHOW-JOB-STATUS).
MF
PREFIX
For a description of the MF and PREFIX operands, see paragraph "General macro operands" .
Their permitted values are indicated at the beginning of the macro description and in the macro call format.
VERSION=
Specifies which version of BS2000 the macro expansion is to be compatible with.
0
Default value; the macro expansion is compatible with JV <= V8.7.
The operand MF=D/C, which generates a DSECT or CSECT respectively, is not supported by this version (see note on DSECT).
1
The macro expansion is compatible with JV V10.0.
2
The macro expansion is compatible with JV V11.0 and V11.2.
3
The macro expansion is compatible with JV V12.0.
4
The macro expansion is compatible with JV >= V13.0C.
Notes concerning the DSECT
Calling the macro with the operands MF=D and VERSION=1/2/3/4 generates a DSECT for the operand list of the CATJV macro of the corresponding version.
A DSECT for the macro with VERSION=0 is generated by calling the macro IDJCA [D][,prefix].
Note on the assignment of access rights using a basic ACL:
A basic ACL is activated if basic ACL rights are specified for at least one authorized user (in the OWNERAR, GROUPAR or OTHERAR operand) When a basic ACL is activated, the rights for a user group that is not specified are set as though BASIC-ACL=NO-ACCESS (neither write nor read access rights) was specified for this user group.
Return information and error flags
see paragraph Messages - Macro level
DSECT
CATJV CATJV MF=D,VERSION=4 1 *********************************************************************** 1 * VERSION 410 1 *********************************************************************** 1 * C A T J V P A R A M E T E R L I S T * 1 *********************************************************************** 1 #INTF REFTYPE=REQUEST, C 1 INTNAME=CATJV,INTCOMP=004 1 CATJV DSECT 1 *********************************************************************** 1 * UNIT=41, FUNCTION=4, VERSION=<PARAMETER VERSION> * 1 *********************************************************************** 1 FHDR MF=(C,IDJC) 2 DS 0A 2 IDJCFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 IDJCIFID DS 0A 0 INTERFACE IDENTIFIER 2 IDJCFCTU DS AL2 0 FUNCTION UNIT NUMBER 2 * BIT 15 HEADER FLAG BIT, 2 * MUST BE RESET UNTIL FURTHER NOTICE 2 * BIT 14-12 UNUSED, MUST BE RESET 2 * BIT 11-0 REAL FUNCTION UNIT NUMBER 2 IDJCFCT DS AL1 2 FUNCTION NUMBER 2 IDJCFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 IDJCRET DS 0A 4 GENERAL RETURN CODE 2 * 2 * GENERAL_RETURN_CODE CLEARED (X'00000000') MEANS 2 * REQUEST SUCCESSFUL PROCESSED AND NO ADDITIONAL INFORMATION 2 * 2 IDJCSRET DS 0AL2 4 SUB RETURN CODE 2 IDJCSR2 DS AL1 4 SUB RETURN CODE 2 2 * ALWAYS CLEARED (X'00') IF MAIN_RETURN_CODE IS X'FFFF' 2 * Standard subcode2 values as defined by convention: 2 IDJCR2OK EQU X'00' All correct, no additional info 2 IDJCR2NA EQU X'01' Successful, no action was necessary 2 IDJCR2WA EQU X'02' Warning, particular situation 2 IDJCSR1 DS AL1 5 SUB RETURN CODE 1 2 * 2 * GENERAL INDICATION OF ERROR CLASSES 2 * 2 * CLASS A X'00' FUNCTION WAS SUCCESSFULLY PROCESSED 2 * CLASS B X'01' - X'1F' PARAMETER SYNTAX ERROR 2 * CLASS C X'20' INTERNAL ERROR IN CALLED FUNCTION 2 * CLASS D X'40' - X'7F' NO CLASS SPECIFIC REACTION POSSIBLE 2 * CLASS E X'80' - X'82' WAIT AND RETRY 2 * 2 IDJCRFSP EQU X'00' FUNCTION SUCCESSFULLY PROCESSED 2 IDJCRPER EQU X'01' PARAMETER SYNTAX ERROR 2 * 3 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'01' - X'1F' 2 IDJCRFNS EQU X'01' CALLED FUNCTION NOT SUPPORTED 2 IDJCRFNA EQU X'02' CALLED FUNCTION NOT AVAILABLE 2 IDJCRVNA EQU X'03' INTERFACE VERSION NOT SUPPORTED 2 * 2 IDJCRAER EQU X'04' ALIGNMENT ERROR 2 IDJCRIER EQU X'20' INTERNAL ERROR 2 IDJCRCAR EQU X'40' CORRECT AND RETRY 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'40' - X'7F' 2 IDJCRECR EQU X'41' SUBSYSTEM (SS) MUST BE CREATED 2 * EXPLICITELY BY CREATE-SS 2 IDJCRECN EQU X'42' SS MUST BE EXPLICITELY CONNECTED 2 * 2 IDJCRWAR EQU X'80' WAIT FOR A SHORT TIME AND RETRY 2 IDJCRWLR EQU X'81' " LONG " 2 IDJCRWUR EQU X'82' WAIT TIME IS UNCALCULABLY LONG 2 * BUT RETRY IS POSSIBLE 2 * 2 GLOBALLY DEFINED ISL ERROR CODES IN CLASS X'80' - X'82' 2 IDJCRTNA EQU X'81' SS TEMPORARILY NOT AVAILABLE 2 IDJCRDH EQU X'82' SS IN DELETE / HOLD 2 * 2 IDJCMRET DS 0AL2 6 MAIN RETURN CODE 2 IDJCMR2 DS AL1 6 MAIN RETURN CODE 2 2 IDJCMR1 DS AL1 7 MAIN RETURN CODE 1 2 * 2 * SPECIAL LAYOUT OF LINKAGE_MAIN_RETURN_CODE (YYYY IN X'00XXYYYY') 2 * 2 IDJCRLNK EQU X'FFFF' LINKAGE ERROR / REQ. NOT PROCESSED 2 IDJCFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 *********************************************************************** 1 * END OF STANDARD HEADER. START OF SPECIAL CATJV PARAMETER LIST * 1 *********************************************************************** 1 IDJCHDRI EQU X'00290404',4 1 IDJRDPAS DS CL4 READ PASSWORD 1 DS XL12 RESERVED 1 IDJWRPAS DS CL4 WRITE PASSWORD 1 DS XL12 RESERVED 1 IDJRETPD DS H RETENTION PERIOD 1 IDJCFLAG DS X FLAGS 1 IDJSTATE EQU X'80' 7-7 1=UPDATE, 0=NEW (STATE) 1 IDJACCES EQU X'40' 6-6 1=READ, 0=WRITE(ACCESS) 1 IDJSHARE EQU X'20' 5-5 1=YES, 0=NO (SHARE) 1 IDJRPN EQU X'10' 4-4 1=RDPASS NULL,STATE=U 1 IDJWPN EQU X'08' 3-3 1=WRPASS NULL,STATE=U 1 IDJRETPN EQU X'04' 2-2 1=RETPD NULL, STATE=U / 1 * RETPD NOT NULL,STATE=NEW 1 IDJACCEN EQU X'02' 1-1 1=ACCESS NULL,STATE=U 1 IDJSHARN EQU X'01' 0-0 1=SHARE NULL, STATE=U 1 * 1 IDJCFLG1 DS X FLAGS 1 IDJCENCR EQU X'80' 7-7 0=YES, 1=NO 1 * (ENCRYPTION) 1 IDJTYPE EQU X'00' 6-6 NOT USED (DEL. V11.2) 1 IDJMONJV EQU X'20' 5-5 1=MONJV=NO,STATE=UPDATE 1 IDJCP2 EQU X'10' 4-4 1=P2 CALLER,0=P1 CALLER 1 IDJCECT EQU X'08' 3-3 1=SET BY CMD PROCESSING 1 IDJBACLN EQU X'04' 2-2 1=SET BASIC-ACL = NONE 1 IDJBACLS EQU X'02' 1-1 1=SET BASIC-ACL = STD 1 IDJNSTEX EQU X'01' 0-0 1=SET NOSTEP=EXISTING 1 * 1 IDJJAR DS 0X ACCESS RIGHTS 1 IDJOWNER DS X OWNER 1 IDJGROUP DS X GROUP 1 IDJOTHER DS X OTHERS 1 * 1 IDJJAUS EQU X'80' 7-7 1=USER CLASS SPECIFIED 1 IDJJARS EQU X'40' 6-6 1=READ SPECIFIED 1 IDJJAWS EQU X'20' 5-5 1=WRITE SPECIFIED 1 IDJJARO EQU X'08' 3-3 1=SET READ 1 IDJJAWO EQU X'04' 2-2 1=SET WRITE 1 * 1 IDJCFLG2 DS X FLAGS 1 IDJGRDN EQU X'80' 7-7 :S: GUARDS = *NONE 1 IDJPVSS EQU X'10' 4-4 :S: GUARD PUBSET SPECIFIED 1 IDJRDGS EQU X'08' 3-3 :S: READ GUARD SPECIFIED 1 IDJWRGS EQU X'04' 2-2 :S: WRITE GUARD SPECIFIED 1 IDJMANSP EQU X'02' 1-1 :S: MANCLAS SPECIFIED 1 * 1 IDJPRFLG DS X PROTECT FLAG 1 IDJPRNSP EQU X'80' 7-7 :S: PROTECT NOT SPEC(DEFAULT) 1 IDJPRSTD EQU X'40' 6-6 :S: PROTECT STD SPECIFIED 1 IDJACCSP EQU X'08' 3-3 :S: ACCESS SPECIFIED 1 IDJSHASP EQU X'04' 2-2 :S: SHARE SPECIFIED 1 IDJRDPSP EQU X'02' 1-1 :S: RDPASS SPECIFIED 1 IDJWRPSP EQU X'01' 0-0 :S: WRPASS SPECIFIED 1 DS X RESERVED 1 * 1 IDJRDG DS CL18 READ GUARD 1 IDJWRG DS CL18 WRITE GUARD 1 IDJPUBS DS CL4 GUARD PUBSET 1 IDJMANCL DS CL8 MANCLAS 1 * 1 IDJJV1 DS CL54 JVNAME 1 IDJJV2 DS CL54 RENAME JVNAME 1 DS CL54 RESERVED 1 DS A RESERVED 1 DS CL16 RESERVED 1 IDJCJVS DS A RESERVED 1 IDJPLLEN EQU *-CATJV LENGTH 1 *********************************************************************** 1 SPACE