This macro shows the definitions of the access conditions.
Macro | Operands |
SHWSAC | MF = D / L / C / M / E ,PREFIX = P / <name 1> ,MACID = ROW / <name 3> ,MGMTPRE = P / <name 1> ,MGMTMAC = ROZ / <name 3> ,XPAND = PARAM / OUTPUT ,PARAM = <name 1..8> ,GUARD* = <c-string: filename 1..40 without-gen-vers with-wild> / <c-string: partial-filename 2..40 with-wild> / <var: char(40)> / (<reg: A(char(40))>) ,SUBTYPE = *ALL / *USER / *GROUP / *OTHER / *ALLUSER / <var: enum SUBTYPE> / (<reg: enum SUBTYPE>) ,SUBIDS = *ALL / array(20): <c-string: name 1..8> / <var: char(8)> / (<reg: A(char(8))>) ,VIEW = *CONDITIONS / *ADMISSION <var: enum VIEW> / (<reg: enum VIEW>) ,INFORM = *ADM / *ATTR / *ALL / *NAME / <var: enum INFORM> / (<reg: enum INFORM>) ,OUTAREA = structure(2): (1) address: <label> / (<reg: pointer>) |
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. The values specified for SUBTYPE refer to the DSECT of the SACMGMT macro.
MGMTPRE and MGMTMAC
specify the prefix for the global DSECTs, constants and equates. This prefix consists of the values specified for the two operands MGMTPRE and MGMTMAC, which are concatenated in this order.
If a prefix is used, it must match the prefix specified for the PREFIX operand in the SACMGMT macro; otherwise, compilation errors will occur.
XPAND
specifies the declarations to be expanded. This operand is valid only for MF=D.
=PARAM
Model of the parameter area.
=OUTPUT
Models of the partial output areas.
GUARD
Name of the guard to be shown. This must be entered in uppercase letters, and may contain wildcards (see the *ADMISSION operand in this macro for a restriction). This operand is mandatory for MF=L.
SUBTYPE, SUBIDS and INFORM are evaluated only for VIEW=*CONDITIONS.
SUBTYPE
specifies the subject type to be shown with VIEW=*CONDITIONS.
=*ALL
All access conditions are to be shown.
=*USER
User IDs whose access conditions are to be shown.
=*GROUP
User group whose access conditions are to be shown.
=*OTHER
The access conditions for all other users are to be shown.
=*ALLUSER
The access conditions for *ALLUSER are to be shown.
SUBIDS
specifies, for SUBTYPE =*GROUP or SUBTYPE=*USER, which individual entries are to be shown. Since only one entry exists for SUBTYPE=*ALLUSER and for SUBTYPE=*OTHER, no SUBIDs can be specified for these two SUBTYPEs.
=*ALL
All access conditions for the specified SUBTYPE are to be shown.
=array(20)
As for the definition of the access conditions, up to 20 subjects whose definitions are to be shown can be specified here.
VIEW
The information to be output can be restricted:
=*CONDITIONS
The access conditions of the guard which the caller of the macro may use to protect his/her objects (as determined by the SCOPE attribute) are output. When used with this operand value the functional scope of the macro is equivalent to that of the SHOW-ACCESS-CONDITIONS command.
=*ADMISSION
The conditions which the caller must fulfill in order to access an object protected with this guard are output. The caller is not told which attribute permits the access. When used with this operand value, the functional scope of the macro is equivalent to that of the SHOW-ACCESS-ADMISSION command.
Only the conditions for the caller are shown; the SCOPE attribute is ignored. If the illegal use of a guard makes the result of evaluation FALSE, this fact is not shown by this option. VIEW=*CONDITIONS must be specified to obtain this information. If *ADMISSION is specified, the guard name must not contain wildcards.
INFORM
specifies which information is to be shown for each guard.
=*ADM
The access conditions of the guard are to be shown.
=*ATTR
The attributes of the guard are to be shown.
=*ALL
The attributes and the access conditions of the guard are to be shown.
=*NAME
Only the name of the guard is to be shown.
OUTAREA
Address and length of the output area.
Layout of the output areas of SHWSAC
The output area contains a compressed representation of the access conditions, which means that it contains variable parts. For this reason, it is not possible to describe the output area with a single DSECT.
The caller must therefore address the individual entries in the output area. The DSECTS required for this are described in detail in the following section.
Since the amount of information to be output depends on the parameters of the call, the following output model is used:
---> | Semantic meaning of the field |
===> | Pointer to the related DSECT. <prefix> is the prefix specified in SHWSAC, concatenated with MACID. <mgmtpref> is the prefix specified in SACMGMT (MGMTPRE concatenated with MGMTMAC). |
... | indicates that this output are is described in more detail in another level. |
======================= Level 1 - Output ===============================
----------
| Output | ====> <prefix>OPUT
----------
| Admin_o| ----> Administration information... (Level 2 - Admin_o)
----------
| Guard_1| ----> The first of n guards to be shown...(Level 2 - Guard_all
---------- - Guard_admin
| | - Guard_cond
... - Guard_nam
| | depending on VIEW and INFORMATION)
?----------
| Guard_n|
----------
======================= Level 2 - Admin_o ==============================
---------- *-----------
| Output | * | Admin_o | ====> <prefix>OPUT
----------* -----------
| Admin_o| | output- | ---> Version of the output structure
----------* | version |
| Guard_1| * -----------
---------- *| #guard | ---> Number of guards included
| | -----------
...
| |
----------
| Guard_n|
----------
======================= Level 2 - Guard_all =========== VIEW = *CONDITIONS
INFORMATION = *ALL
----------
| Output | -------------
---------- | Guard_all | ====> <prefix>GALL
| Admin_o| ** -------------
----------** | Mgmt_part | ---> The attributes of the guard
| Guard_1| ------------- ... (Level 3 Mgmt_part)
----------** | Aconds | ---> The selected access conditions
| | ** ------------- ... (Level 3 Aconds)
...
| |
----------
| Guard_n|
----------
======================= Level 2 - Guard_admin ======= VIEW = *CONDITIONS
INFORMATION = *ATTR
----------
| Output |
----------
| Admin_o| ** -------------
----------** |Guard_admin| ====> <prefix>GATT
| Guard_1| -------------
----------** | Mgmt_part | ---> Attributes of the guard
| | ** ------------- ... (Level 3 Mgmt_part)
...
| |
----------
| Guard_n|
----------
======================= Level 2 - Guard_cond==== VIEW = *ADMISSION ======
or VIEW = *CONDITIONS and
---------- INFORMATION = *ADM
| Output |
----------
| Admin_o| ** -------------
----------** |Guard_cond | ====> <prefix>GCON
| Guard_1| -------------
----------** | Name | ---> The name of the guard
| | * -------------
... * | Aconds | ---> Selected access conditions
... ------------- ... (Level 3 Aconds)
| |
----------
| Guard_n|
----------
======================= Level 2 - Guard_nam ========= VIEW = *CONDITIONS
INFORMATION = *NAME
----------
| Output | ====> <prefix>OUTP
----------
| Admin_o| ---> Administration information ... (Level 2 - Admin_o)
----------
| Name_1 | ---> The name of the first of n guards
----------
| |
...
| |
----------
| Name_n |
----------
======================= Level 3 - Mgmt_part===========================
* -----------
* |Mgmt_part| ====> <prefix>GATT
----------- * -----------
| Guard |* | Version | ---> Version of the guard
----------- -----------
|Mgmt_part| | Name | ---> Name of the guard
----------- -----------
| Aconds |* | Scope | ---> User scope
----------- * -----------
* | Comment | ---> Comment text
* -----------
*| Cr-Date | ---> Time stamp of the creation date
-----------
| Lm-Date | ---> Time stamp of the last modification
-----------
======================= Level 3 - Aconds===============================
------------
----------- | Aconds | ====> <prefix>ACOS
|Guard_all| * ------------
----------- * | Admin_Aco| ---> Administration information
|Mgmt_part| * ------------ ... (Level 4 Admin_Aco)
-----------* | Acond_1 | ---> 1st access condition
| Aconds | ------------ ... (Level 4 - Acond_All)
-----------* | |
* ...
* | |
* ------------
| Acond_n |
------------
======================= Level 4 - Admin_Aco ===============================
-------------
* | Admin_Aco | ====> <prefix>ACOS
----------- * -------------
| Aconds | * | User_n | ---> Number of user-specific access
-----------* ------------- conditions
|Admin_Aco| | Group_n | ---> Number of group-specific access
-----------* ------------- conditions
| Acond_1 | * | Others_n | ---> Guard contains OTHERS condition:
----------- * ------------- 0 - No, 1 - Yes
| Acond_2 | * | Alluser_n | ---> Guard contains ALLUSER condition:
----------- ------------- 0 - No, 1 - Yes
| |
...
| |
-----------
| Acond_3 |
-----------
======================= Level 4 - Acond_all================================
-------------
| Acond_All | ===> <prefix>ACON
----------- *-------------
| Aconds | * | Identifier| ---> Name and type of the access condition
----------- * -------------
|Admin_Aco| * | Size | ---> Size of the access condition
-----------* -------------
| Acond_1 | | Admission | ---> Type of access condition
-----------* -------------
| Acond_2 | * | Time_cond | ---> Compressed time condition
----------- * ------------- ...(Level 5 Time_cond)
| | * | Date_cond | ---> Compressed date condition
... *------------- ...(Level 5 Date_cond)
... | Week_cond | ---> Weekday condition
| | ------------- ...(Level 5 Week_cond)
----------- | Priv_cond | ---> Privilege condition
| Acond_3 | ------------- ...(Level 5 Priv_cond)
----------- | Prog_cond | ---> Compressed program condition
------------- ...(Level 5 Prog_cond)
======================= Level 5 Time_cond ================================= ------------- | Acond | ----------- ------------- |Time_cond| ===> <prefix>TCON | Identifier| *----------- ------------- * | Kind | ---> Kind of condition (admission or | Size | * ----------- exclusion) - see notes below ------------- * | Int_n | ---> Number of periods (up to 4!) | Admission | * ----------- -------------* | Int_1 | ---> 1st period (low,high) | Time_cond | ----------- -------------* | | | Date_cond | * ... ------------- * | | | Week_cond | * ----------- ------------- * | Int_n | ---> Last period | Priv_cond | *----------- ------------- | Prog_cond | -------------
======================= Level 5 Date_cond================================ ------------- | Acond | ------------- | Identifier! ----------- ------------- |Date_cond| ===> <prefix>DCON | Size | *----------- ------------- * | Kind | ---> Kind of condition (admission or | Admission | * ----------- exclusion) - see notes below ------------- * | Int_n | ---> Number of periods (up to 4!) | Time_cond | * ----------- -------------* | Int_1 | ---> First period (low,high) | Date_cond | ----------- -------------* | | | Week_cond | * ... ------------- * | | | Priv_cond | * ----------- ------------- * | Int_n | ---> Last period | Prog_cond | *----------- -------------
======================= Level - 5 Week_cond ==============================
-------------
| Acond |
-------------
| Identifier|
-------------
| Size | -----------
------------- |Week_cond| ===> <prefix>WCON
| Admission | *-----------
------------- * | Kind | ---> Kind of condition (admission or
| Time_cond | * ----------- exclusion) - see notes below
------------- * | MO | ---> Value for Monday (YES or NO)
| Date_cond | * -----------
-------------* | TU | ---> Value for Tuesday (YES or NO)
| Week_cond | -----------
-------------* | |
| Priv_cond | * ...
------------- * | |
| Prog_cond | * -----------
------------- * | SU | ---> Value for Sunday (YES or NO)
*-----------
======================= Level - 5 Priv_cond ===============================
-------------
| Acond |
-------------
| Identifier|
-------------
| Size |
-------------
| Admission | -----------
------------- |Priv_cond| ===> <prefix>PVCO
| Time_cond | *-----------
------------- * | Kind | ---> Kind of condition (admission or
| Date_cond | * ----------- exclusion) - see notes below
------------- * | TSOS | ---> Value for privilege TSOS
| Week_cond | * -----------
-------------* | USRADM | ---> Value for privilege USRADM
| Priv_cond | -----------
-------------* | |
| Prog_cond | * ...
------------- * | |
* -----------
* | SECADM | ---> Value for privilege SECADM
*-----------
======================= Level 5 - Prog_cond ===============================
-------------
| Acond |
-------------
| Identifier|
-------------
| Size |
-------------
| Admission |
------------- -------------
| Time_cond | | Prog_cond | ====> <prefix>PCON
------------- -------------
| Date_cond | | Kind | ---> Kind of condition (admission or
------------- * ------------- exclusion) - see notes below
| Week_cond | * | Prog_n | ---> Number of programs
------------- * ------------- ... (Level 6 Prog_All)
| Priv_cond | * | Prog_1 | ---> 1st compressed program
-------------* | |
| Prog_cond | ...
-------------* | |
* | |
* -------------
* | Prog_n | ---> Last compressed program
-------------
======================= Level 6 - Prog_All ================================ ------------- | Prog_All | ====> <prefix>PRG ------------- | Type | ---> Type of program (file, phase or module) ------------- | all_# | ---> Length of the following program name ------------- | lib_# | ---> Length of the library name in the program name ------------- | elem_# | ---> Length of the library member name in the program name ------------- | vers_# | ---> Length of the version number in the program name ------------- | name | ---> The program name -------------
Notes on evaluation of the access condition output area
The following must be noted when evaluating conditions:
The condition structure shown above is valid only if the kind of condition ’Kind’ does not contain *NO for CONDITION_KIND. (CONDITION_KIND is defined in the SACMGMT macro.)
If CONDITION_KIND contains *NO, only the kind of condition is placed in the output area.
The behavior described above for CONDITION_KIND also applies analogously to Time_cond, Date_cond, Week_cond, Priv_cond and Prog_cond.
The output structure of an access condition could thus look like this (excerpt from the output):
======================= Level 4 - Acond_All =============================== ------------------------ | Acond_All | ------------------------ | Identifier | ------------------------ | Size | ------------------------ | Admission | ------------------------ | Time_cond: Kind | ---> contains NO ------------------------ | Date_cond: Kind | ---> contains NO ------------------------ | Week_cond: Kind | ---> contains NO ------------------------ | Priv_cond: Kind | ---> contains NO ------------------------ | Prog_cond: Kind | ---> contains NO ------------------------
Application notes
If the indicator prefix.RONOMOR is set in the parameter area, there are further guards matching the selection criteria which would not fit into the available output area.
These guards can be read by calling the procedure again. Note, however, that the parameter block must not be modified before this second call is issued.
The field prefix.RONOUS# in substructure &prefix.ROWOPUT of the parameter area shows the length of the information placed in the parameter area.
If the guards are on a pubset which is accessible via RFA, the maximum supported output area size is 64 Kbytes, i.e only 64 Kbytes are placed in the output area, even if a larger (>64 Kbytes) is specified. If the information to be returned is longer than 64 Kbytes, the call must be repeated as many times as necessary to transfer all the information.
The field prefix.ROWOUTV in the administration information indicates the version of the output structure. However, this information is not important until such time as several versions of SHWSAC with different output structures exist.
If SHWSAC is called with VIEW=*ADMISSION, the access condition which is found is returned only if the value of the field &prefix.ROWAADM is not *NO.
If the field prefix.ROWAADM of the access condition contains *NO, or if no matching access condition is found, the return code X’1030’ (see the DSECT of the MSGGUAD macro) is returned.
If SHWSAC is called with VIEW=*ADMISSION, the output has the same structure as for a call with VIEW=*CONDITIONS,INFORM=*ADM, (see Level 2 - Guards_Cond).
If, in an /ADD-ACCESS-CONDITIONS or /MODIFY-ACCESS-CONDITIONS command or in the MODSAC macro, the VERSION operand for the PROGRAM condition was set to *ANY, the version field in the output likewise contains the string *ANY.
The time stamps for CREATION-DATE and LAST-MODIFICATION-DATE are output in UTC (universal time coordinate) format.
The MODSAC interface permits only the input of uppercase letters. Care must therefore be taken that the identifiers in the SUBIDS operand contain only uppercase letters.
Specifying lowercase letters does not result in an error, but it does mean that no access conditions will be selected and returned.
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 output area not allocated with the required length or not accessible | |
X’40’ | X’1004’ | Memory for the parameter area not allocated with the required length or cannot be written | |
X’40’ | X’1005’ | The output area is too small | |
X’40’ | X’1007’ | The specified guard does not exist | |
X’80’ | X’1009’ | The specified guard is locked by another task | |
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’1016’ | Error in the MRS communication facility | |
X’40’ | X’1017’ | Unknown user ID | |
X’40’ | X’1018’ | The remote system is not available | |
X’40’ | X’1020’ | No more memory space available | |
X’40’ | X’1021’ | BCAM connection error | |
X’40’ | X’1022’ | The BCAM connection has been interrupted | |
X’40’ | X’1023’ | There is no guard matching the selection criteria | |
X’40’ | X’1024’ | Use of the guard is not permitted | |
X’40’ | X’1028’ | GUARDS is of incorrect type | |
X’40’ | X’1029’ | GUARDS is not available on the remote system | |
X’80’ | X’1030’ | The user condition in the guard cannot be fulfilled |