With this macro, GUARDS is called from within a program in order to execute condition evaluation. The program thus becomes an object management system and GUARDS can then be used for protection of objects belonging to the program.
Macro | Operanden |
CHKSAC | MF = D / L / C / M / E ,PREFIX = P / <name 1> ,MACID = ROV / <name 3> ,PARAM =<name 1..8> ,GUARD = <c-string: filename 1..24 without-gen-vers> / <var: char(24)> / (<reg: A(char(24))>) ,OBJOWN = *OWN / <c-string: name 1..8> / <var: char(8)> / (<reg: A(char(8))>) ,ACCTSN = *OWN / <c-string: name 1..4> / <var: char(4)> / (<reg: A(char(4))>) ,ACCUID = *OWN / <c-string: name 1..8> / <var: char(8)> / (<reg: A(char(8))>) ,EVAL * = *ACCESS / *SHOW / <var: enum EVAL> / (<reg: enum EVAL>) ,TIME = *NO / *YES ,DATE = *NO / *YES ,WEEKDAY = *NO / *YES ,PRIV = *NO / *YES ,PROG = *NO / *YES |
For a description of the parameters MF, PREFIX, MACID, PARAM see the “Executive Macros” manual [16].
Operands marked with an asterisk (*) are mandatory operands for MF=L.
GUARD
Name of the guard with which the conditions are to be checked. This name must be entered in uppercase letters.
OBJOWN
Owner of the object protected with the guard. *OWN sets the caller’s own user ID and is the default.
Only one of the two following operands ACCTSN and ACCUID may be specified.
ACCTSN
Task sequence number of the task which executes the access. *OWN sets the caller’s own TSN and is the default.
ACCUID
User ID for which the access check is performed. This user ID must exist. This operand may be specified only in programs which run under a task with the TSOS privilege. *OWN sets the caller’s own user ID and is the default.
EVAL
This specifies how the check is to be executed. This operand is mandatory for MF=L.
=*ACCESS
GUARDS is to check whether access to the protected object is permitted.
=*SHOW
GUARDS is to check whether the user may see the guard. This has no effect on the protected objects. GUARDS checks whether access is always permitted or permitted only under certain circumstances.
If *SHOW is specified, the following parameters of this macro are ignored.
TIME
specifies whether a time condition is to be ignored:
=*NO
The time condition is not ignored.
=*YES
The time condition is ignored.
DATE
specifies whether a date condition is to be ignored:
=*NO
The date condition is not ignored.
=*YES
The date condition is ignored.
WEEKDAY
specifies whether a weekday condition is to be ignored:
=*NO
The weekday condition is not ignored.
=*YES
The weekday condition is ignored.
PRIV
specifies whether a privilege condition is to be ignored:
=*NO
The privilege condition is not ignored.
=*YES
The privilege condition is ignored.
PROG
specifies whether a program condition is to be ignored:
=*NO
The program condition is not ignored.
=*YES
The program condition is ignored.
Macro return codes
SC2 | SC1 | Maincode | Meaning |
X’01’ | X’1000’ | The specified operand value lies outside the permitted range. The invalid operand is stored as a symbolic value in SC2 | |
X’20’ | X’1001’ | An internal error has occurred. A SERSLOG entry has been written for further analysis | |
X’40’ | X’1002’ | Syntax error in the guard name | |
X’40’ | X’1003’ | Memory for the parameter area not allocated with the required length | |
X’40’ | X’1007’ | The specified guard does not exist | |
X’40’ | X’1012’ | The specified catalog is not defined or not accessible | |
X’40’ | X’1013’ | The pubset is not known to the GUARDS administration (the guards catalog was probably not opened at IMPORT-PUBSET) | |
X’40’ | X’1014’ | The user is not authorized to execute this function | |
X’40’ | X’1019’ | The user ID executing access is unknown | |
X’40’ | X’1020’ | No more memory space available | |
X’40’ | X’1024’ | Use of the guard is not permitted |
Example
This example shows how part of a program can be protected with GUARDS.
The program contains parts which are to be accessible only to specific program users. The program must contain definitions indicating which parts of the program are to be protected and which guards are to be used for this.
In order to protect the program parts, the appropriate guards must be created so that they can be checked by means of the CHKSAC macro before the protected parts of the program are executed.
The CHKSAC macro determines whether or not the conditions defined in the guard are fulfilled by the current program user.
Example for protecting part of a program with GUARDS, using the CHKSAC macro
BSPL CSECT
R10 EQU 10
BALR R10,0
USING *,R10
* ***************************************************
* *
* THE PARAMETER AREA IS FILLED AGAIN WITH ITS *
* ORIGINAL CONTENTS BEFORE EACH MF=E CALL *
* *
MVC PARAMFC(PROV#),PARAMFL
* *
* AND THEN MODIFIED IF NECESSARY *
* *
CHKSAC MF=M,GUARD=GUARDNAM
* *
* ***************************************************
* *
* EXECUTION OF THE MACRO:
* *
CHKSAC MF=E,PARAM=PARAMFC
* *
* ***************************************************
* *
* CHECKING THE RETURN CODE: *
* *
CLC PROVMRET,=Y(PRMTSUCC)
BNE RCNOTOK
* *
* ***************************************************
* *
* CHECKING THE RESULT: *
* *
CLI PROVCHKR,PROVCYES
BNE BSPLNO
* *
* ***************************************************
* THIS PART OF THE PROGRAM IS PROTECTED AND IS *
* EXECUTED ONLY IF THIS IS PERMITTED BY THE *
* GUARD MYGUARD *
* *
MVC TEXT,OKTEXT
B ENDE
* *
* ***************************************************
BSPLNO EQU *
* IF THE GUARD MYGUARD DOES NOT PERMIT EXECUTION *
* OF THE PROTECTED PART OF THIS PROGRAM; THIS *
* PART IS EXECUTED INSTEAD *
* *
B ENDE
* *
* ***************************************************
* *
RCNOTOK EQU *
* ERROR HANDLING FOR A RETURN CODE WHICH IS NOT *
* "OK". THE REACTION DEPENDS ON THE TASK. *
* IF PROGRAM EXECUTION IS TO CONTINUE (THIS IS, *
* FOR EXAMPLE, POSSIBLE AFTER RC 1007), THEN *
* THE PROTECTED PART OF THE PROGRAM SHOULD NOT *
* BE EXECUTED *
MVC TEXT,RCTEXT
B ENDE
* *
* ***************************************************
* *
ENDE EQU *
WROUT MESSAGE,WRFEHL
WRFEHL EQU *
TERM
* *
* ***************************************************
* *
* THE PARAMETER AREA (WHEN THE MACRIO IS CALLED, *
* REGISTER 1 CONTAINS THE ADDRESS PARAMFC): *
PARAMFC DS 0F
CHKSAC MF=C
* *
* ***************************************************
* *
* THE AREA PARAMFL NORMALLY REMAINS UNCHANGED DURING*
* EXECUTION OF THE ENTIRE PROGRAM AND IS MOVED TO *
* THE PARAMETER AREA PAMAMFC BEFORE EACH MF=E CALL *
* (SEE MVC ABOVE) *
* *
PARAMFL DS 0F
CHKSAC EVAL=*ACCESS,MF=L
* *
* ***************************************************
* *
* THE VALUE FOR A PARAMETER WHICH IS TO BE MODIFIED:*
* *
GUARDNAM DC CL24'MYGUARD'
* *
* ***************************************************
* *
MELDUNG DC Y(MELDENDE-MELDUNG)
DS CL2
DC X'01'
TEXT DC 'ACCESS CONDITIONS IN MYGUARD: ACCESS NOT PERMITTED'
MELDENDE EQU *
OKTEXT DC 'ACCESS CONDITIONS IN MYGUARD: ACCESS PERMITTED'
RCTEXT DC '..... RETURN CODE IS NOT 0000 ..... '
* *
* ***************************************************
* *
* THE NAMES (EQUATES) OF THE RETURN CODES ARE IN *
* THE FOLLOWING DSECT *
* *
MSGGUAD MF=D
* *
* IF NECESSARY; THE NAMES CAN BE GENERATED AS A *
* DSECT IN THE PARAMETER AREA. HOWEVER, SINCE MF=C *
* IS USED AT THE SAME TIME, THESE NAMES MUST HAVE *
* A DIFFERENT PREFIX *
* *
CHKSAC MF=D,PREFIX=X
* *
* ***************************************************
END
Procedure for calling the sample program
/PROC A,(&BIBL),SUBDTA= /REMARK THE SAMPLE PROGRAM BSPL IS IN LIBRARY BIBL /DELETE-GUARD MYGUARD /STEP /ADD-ACCESS-CONDITION MYGUARD,SUBJECT=USER(($SYSJV.USERID)), ADM=NO /START-PROGRAM *P(&BIBL.,BSPL) /REMARK THE FOLLOWING TEXT WAS OUTPUT BY BSPL: /REMARK ACCESS CONDITIONS IN MYGUARD: ACCESS NOT PERMITTED /MOD-ACCESS-CONDITION MYGUARD,SUBJECT=USER( ($SYSJV.USERID)),ADM=YES ? /START-PROGRAM *P(&BIBL.,BSPL) /REMARK THE FOLLOWING TEXT WAS OUTPUT BY BSPL: /REMARK ACCESS CONDITIONS IN MYGUARD: ACCESS PERMITTED /ENDP