Macro type: type S (E form/L form/D form/C form/M form); see "Macro types"
The CHKFAR macro checks the access rights for the file specified in the call and informs the caller which access rights he/she has for this file. The user may select
whether all access facilities he/she has for the file are to be shown (ignoring any passwords or retention period which may exist) or
whether he/she desires information on a specific access right (including any password protection or retention period defined for the file).
The information is returned to the caller in an output area of the operand list.
For private files: the CHKFAR macro evaluates information from the user catalog only, not from the F1 label.
For tape files: the CHKFAR macro evaluates information from the user catalog, but not from the header record on the tape.
Format
Operation | Operanden |
|
|
| |
| |
|
Operand descriptions
FILE
Specifies the file for which the user wishes to determine or check his/her access rights.
= pathname
Name of the file whose access rights are to be checked, where
<c-string 1..54: filename 1..54>
Pathname means [:catid:][$userid.]filename
catid
Catalog ID: if omitted, the default catalog ID for the current user ID is assumed.
userid
User ID: if omitted, the user ID in the SET-LOGON-PARAMETERS or LOGON command is assumed.
filename
A fully qualified file name.
= addr1
Symbolic address (i.e. the name) of a 54-byte field in the user program which contains the path name of the file to be checked.
= (r)
Number of a register which contains the address of the “addr1” field. The register must be loaded with this address value before the macro is called.
ACCESS
Specifies whether all access rights enjoyed by the user for the specified file are to be returned or whether the file is to be checked for a specific access right for the user. The information is returned in an output area of the operand list.
= *ANY
Information on all access rights which the user possesses for the specified file is placed in an output area of the operand list. Any other possible protection attributes of the file, such as passwords or a retention period, are not evaluated.
= *READ
The system checks whether the caller may read the specified file. Any existing password for the file is also taken into account.
= *WRITE
The system checks whether the caller may write to the specified file. Any existing password or retention period for the file is also taken into account.
= *UPDATE
The system checks whether the caller may read from and write to the specified file. Any existing password or retention period for the file is also taken into account.
= *DELETE
The system checks whether the caller may delete the specified file. Any existing password or retention period for the file is also taken into account.
= *EXEC
The system checks whether the caller may execute the specified file. Any existing password for the file is also taken into account.
MACID
Defines the second through fourth characters of each field name and equate generated when the macro is expanded.
Default value: | MACID = RMZ |
= macid
Three-character string defining the second through fourth characters of the generated field names and equates.
PARAM
Specifies the address of the operand list; it is evaluated only if MF=E applies (see "Macro types").
= addr
Symbolic address (name) of the operand list.
= (r)
Number of the register which contains the address of the operand list. The register must be loaded with this address value before the macro is called.
PREFIX
Specifies the first character of each field name or equate which the assembler generates in the data area when expanding the macro.
Default value: | PREFIX=S. |
= pre
Single-character prefix with which the field names and equates generated by the assembler are to begin.
Return codes
Standard header: ccbbaaaa
The following code relating to execution of the CHKFAR macro is returned in the standard header (cc = SUBCODE2, bb = SUBCODE1, aaaa = MAINCODE):
X'bb' | X'aaaa' | Meaning |
X'00' | X'0000' | The function was executed successfully. |
X'01' | X'6000' | The function could not be executed: the operand list contains an invalid value. |
X'40' | X'6001' | The function could not be executed: the specified file was not found in the catalog. |
X'40' | X'6008' | The function could not be executed: the specified catalog is unknown or was not available. |
X'20' | X'6014' | The function could not be executed: system error. |
X'40' | X'6021' | BCAM connection error |
X'40' | X'6022' | BCAM connection interrupted |
X'01' | X'6040' | The function could not be executed: The operand list was not available or assigned with the necessary length. |
Further return codes, whose meanings are defined by conventions valid for all macros, can be found in the table in chapter "Standard header".
The calling program is terminated if one of the following errors occurs with respect to the parameter list:
the list is not assigned to the caller
the list is not aligned on a word boundary
the list is write-protected.
Description of the output fields
The following information is returned for ACCESS = *ANY:
Access rights: the caller's access rights for the file. Passwords and retention periods are not taken into account.If access control using GUARDS is defined, the guards for the caller are evaluated.
If a BASIC-ACL is in effect, the values from the entry applicable to the caller are used.
If SHARE/ACCESS is in effect, the values are set as follows:
ACCESS SHARE Owner R Owner W Owner X Others R Others W Others X WRITE NO Y Y Y N N N WRITE YES Y Y Y Y Y Y READ NO Y N Y N N N READ YES Y N Y Y N Y Key: R: READ, W: WRITE, X: EXECUTE, Y: YES, N: NO
Where ACCESS = *READ/*WRITE/*UPDATE/*DELETE/*EXEC:
CHECK-RESULT: specifies whether or not the desired access is permitted.
Layout of the operand list
(macro expansion with MF=D and default values for PREFIX and MACID)
CHKFAR MF=D 1 MFCHK MF=D,PREFIX=S,MACID=RMZ,PARAM=, C 1 SUPPORT=(C,D,E,L,M),DMACID=RMZ,SVC=8 2 SRMZ DSECT , 2 *,##### PREFIX=S, MACID=RMZ ##### 1 ****************************************************************** 1 * CHKFAR - PARAMETER AREA * 1 ****************************************************************** 1 #INTF REFTYPE=REQUEST,INTNAME=CHKFAR,INTCOMP=001 1 * 1 SRMZPA DS 0F BEGIN of PARAMETER AREA _INOUT 1 * 1 FHDR MF=(C,SRMZ),EQUATES=NO 2 DS 0A 2 SRMZFHE DS 0XL8 0 GENERAL PARAMETER AREA HEADER 2 * 2 SRMZIFID DS 0A 0 INTERFACE IDENTIFIER 2 SRMZFCTU 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 SRMZFCT DS AL1 2 FUNCTION NUMBER 2 SRMZFCTV DS AL1 3 FUNCTION INTERFACE VERSION NUMBER 2 * 2 SRMZRET DS 0A 4 GENERAL RETURN CODE 2 SRMZSRET DS 0AL2 4 SUB RETURN CODE 2 SRMZSR2 DS AL1 4 SUB RETURN CODE 2 2 SRMZSR1 DS AL1 5 SUB RETURN CODE 1 2 SRMZMRET DS 0AL2 6 MAIN RETURN CODE 2 SRMZMR2 DS AL1 6 MAIN RETURN CODE 2 2 SRMZMR1 DS AL1 7 MAIN RETURN CODE 1 2 SRMZFHL EQU 8 8 GENERAL OPERAND LIST HEADER LENGTH 2 * 1 * 1 SRMZACC DS XL1 ACCESS 001 1 SRMZANY EQU 0 = *ANY 001 1 SRMZREA EQU 1 = *READ 001 1 SRMZWRI EQU 2 = *WRITE 001 1 SRMZUPD EQU 3 = *UPDATE 001 1 SRMZDEL EQU 4 = *DELETE 001 1 SRMZEXE EQU 5 = *EXEC 001 1 * 1 SRMZFILE DS CL54 FILE = pathname 001 1 * 1 SRMZRIF DS XL1 RETURN_INFO 001 1 * Here after: ACCESS_RIGHTS bits returned when ACCESS = *ANY 1 SRMZARR EQU X'80' READ 001 1 SRMZARW EQU X'40' WRITE 001 1 SRMZARE EQU X'20' EXEC 001 1 SRMZARU EQU X'1F' UNUSED 001 1 * Here after: AUTHORIZATION bin-value returned when ACCESS NE *ANY 1 SRMZALW EQU 0 ALLOWED 001 1 SRMZFBD EQU 1 FORBIDDEN 001 1 * 1 SRMZUNU DS XL4 -- MUST BE ZERO -- 001 1 SRMZPA# EQU *-SRMZPA LENGTH OF PARAMETER AREA 001