Limiting Data Source Access: The RESTRICT Attribute

In this section:

How to:

The ACCESS attribute determines what a user can do with a data source.

The optional RESTRICT attribute further restricts a user access to certain fields, values, or segments.

The RESTRICT=VALUE attribute supports those criteria that are supported by the IF phrase. The RESTRICT=VALUE_WHERE attribute supports all criteria supported in a WHERE phrase, including comparison between fields and use of functions. The WHERE expression will be passed to a configured adapter when possible. For MODIFY, VALUE and VALUE_WHERE are synonymous and are internally converted to VALIDATE commands.


Top of page

x
Syntax: How to Limit Data Source Access
...RESTRICT=level, NAME={name|SYSTEM} [,VALUE=test|],$

or

...RESTRICT=VALUE_WHERE, NAME=name,  VALUE=expression; ,$

where:

level

Can be one of the following:

FIELD specifies that the user cannot access the fields named with the NAME parameter.

SEGMENT specifies that the user cannot access the segments named with the NAME parameter.

PROGRAM specifies that the program named with the NAME parameter will be called whenever the user uses the data source (discussed in Program Accounting/Resource Limitation).

SAME specifies that the user has the same restrictions as the user named in the NAME parameter. No more than four nested SAME users are valid.

NOPRINT specifies that the field named in the NAME or SEGMENT parameter can be mentioned in a request statement, but will not appear. This option is not supported with relational data sources.

name

Is the name of the field or segment to restrict. When used after NOPRINT, this can only be a field name. NAME=SYSTEM, which can only be used with value tests, restricts every segment in the data source, including descendant segments. Multiple fields or segments can be specified by issuing the RESTRICT attribute several times for one user.

VALUE

Specifies that the user can have access to only those values that meet the test described in the test parameter.

test

Is the value test that the data must meet before the user can have access to it. The test is an expression supported in an IF phrase.

VALUE_WHWERE

Specifies that the user can have access to only those values that meet the test described in the expression parameter.

expression

Is the value test that the data must meet before the user can have access to it. The test is an expression supported in an WHERE phrase.

Note: For write access, if name is a segment name, a MATCH key ON MATCH/NOMATCH is performed. For any other name, a validate is done without a MATCH.



Example: Restricting Access to Values Using VALUE_WHERE

Add the following DBA declarations to the end of the GGSALES Master File. These declarations give USER1 access to the West region and to products that start with the letter C:

END                                                            
DBA = USERD,$                                                   
USER = USER1, ACCESS = R, NAME = SALES01, RESTRICT = VALUE_WHERE,
       VALUE = REGION EQ 'West' AND PRODUCT LIKE 'C%'; ,$     

The following request sets the password to USER1 and sums dollar sales and units by REGION, CATEGORY, and PRODUCT:

SET USER = USER1  
TABLE FILE GGSALES
SUM DOLLARS UNITS 
BY REGION         
BY CATEGORY       
BY PRODUCT        
END               

The output only displays those regions and products that satisfy the WHERE expression in the Master File:

Region       Category     Product           Dollar Sales  Unit Sales
------       --------     -------           ------------  ----------
West         Coffee       Capuccino               915461       72831
             Food         Croissant              2425601      197022
             Gifts        Coffee Grinder          603436       48081
                          Coffee Pot              613624       47432

If the RESTRICT=VALUE_WHERE attribute is changed to a RESTRICT=VALUE attribute, the expression is not valid, the following message is generated, and the request does not execute:

(FOC002) A WORD IS NOT RECOGNIZED:  LIKE 'C%'


Example: Limiting Data Source Access
USER=BILL ,ACCESS=R ,RESTRICT=SEGMENT ,NAME=COMPSEG,$ 

Top of page

x
Restricting Access to a Field or a Segment

How to:

The RESTRICT attribute identifies the segments or fields that the user will not be able to access. Anything not named in the RESTRICT attribute will be accessible.

Without the RESTRICT attribute, the user has access to the entire data source. Users may be limited to reading, writing, or updating new records, but every record in the data source is available for the operation.



x
Syntax: How to Restrict Access to a Field or a Segment
...RESTRICT=level,  NAME=name,$

where:

level

Can be one of the following:

FIELD specifies that the user cannot access the fields named with the NAME parameter.

SEGMENT specifies that the user cannot access the segments named with the NAME parameter.

SAME specifies that the user has the same restrictions as the user named in the NAME parameter.

NOPRINT specifies that the field named in the NAME or SEGMENT parameter can be mentioned in a request statement but will not appear. When used after NOPRINT, NAME can only be a field name. This option is not supported with relational data sources.

name

Is the name of the field or segment to restrict. When used after NOPRINT, this can only be a field name.

NAME=SYSTEM, which can only be used with value tests, restricts every segment in the data source, including descendant segments. Multiple fields or segments can be specified by issuing the RESTRICT attribute several times for one user.

Note:



Example: Restricting Access to a Segment

In the following example, Bill has read-only access to everything in the data source except the COMPSEG segment:

USER=BILL ,ACCESS=R ,RESTRICT=SEGMENT ,NAME=COMPSEG,$


Example: Reusing a Common Set of Access Restrictions

In the following example, both Sally and Harry have the same access privileges as BILL. In addition, Sally is not allowed to read the SALARY field.

USER=BILL, ACCESS=R, RESTRICT=VALUE, NAME=IDSEG,
     VALUE=DIVISION EQ 'WEST',$
USER=SALLY, ACCESS=R, RESTRICT=SAME, NAME=BILL,$
                      RESTRICT=FIELD, NAME=SALARY,$
USER=HARRY, ACCESS=R, RESTRICT=SAME, NAME=BILL,$

Note: A restriction on a segment also affects access to its descendants.


Top of page

x
Restricting Access to a Value

How to:

You can also restrict the values to which a user has access by providing a test condition in your RESTRICT attribute. The user is restricted to using only those values that satisfy the test condition.

You can restrict values in one of two ways: by restricting the values the user can read from the data source, or restricting what the user can write to a data source. These restrictions are two separate functions: one does not imply the other. You use the ACCESS attribute to specify whether the values the user reads or the values the user writes are restricted.

You restrict the values a user can read by setting ACCESS=R and RESTRICT=VALUE. This type of restriction prevents the user from seeing any data values other than those that meet the test condition provided in the RESTRICT attribute. A RESTRICT attribute with ACCESS=R functions as an involuntary IF statement in a report request. Therefore, the syntax for ACCESS=R value restrictions must follow the rules for an IF test in a report request.

Note: RESTRICT=VALUE is not supported in Maintain.

You restrict the values a user can write to a data source by setting ACCESS=W and RESTRICT=VALUE. This type of restriction, which functions as a VALIDATE command in MODIFY, limits the actual values a user can enter. Therefore, the syntax for ACCESS=W value restrictions must follow the rules for a VALIDATE command in MODIFY. You can also use ACCESS=W and RESTRICT=VALUE to limit the data values in the data source for which a user can provide new values. When ACCESS=W, the user will be able to access all data values in the data source. The user will simply be prohibited from entering certain values or new values for certain existing values.

If you want to prevent a user both from entering certain values and from seeing other values, you must issue two RESTRICT attributes: one with ACCESS=W, which limits the values a user can write or alter, and one with ACCESS=R, which limits the values the user can see. ACCESS=RW is meaningless with a RESTRICT=VALUE statement.

Note: You can display a table listing users and their access privileges with the EX DBATABLE command described in Displaying the Decision Table. For DBATABLE to work properly, you must list all users who have no value restrictions prior to users with value restrictions in the Master File.



x
Syntax: How to Restrict Values a User Can Read
...ACCESS=R, RESTRICT=VALUE, NAME=name, VALUE=test,$

where:

name

Is the name of the segment which, if referenced, activates the test. To specify all segments in the data source, specify NAME=SYSTEM.

test

Is the test being performed.



Example: Restricting Values a User Can Read
USER=TONY, ACCESS=R, RESTRICT=VALUE, NAME=IDSEG,
     VALUE=DIVISION EQ 'WEST',$

With this restriction, Tony can only see records from the western division.

You type the test expression after VALUE=. The syntax of the test condition is the same as that used by the TABLE command to screen records, except the word IF does not precede the phrase. (Screening conditions in the TABLE command are discussed in the Creating Reports manual.) Should several fields have tests performed on them, separate VALUE attributes must be provided. Each test must name the segment to which it applies. For example:

USER=DICK, ACCESS=R, RESTRICT=VALUE, NAME=IDSEG,
     VALUE=DIVISION EQ 'EAST' OR 'WEST',$
     NAME=IDSEG,
     VALUE=SALARY LE 10000,$

If a single test condition exceeds the allowed length of a line, it can be provided in sections. Each section must start with the attribute VALUE= and end with the terminator (,$). For example:

USER=SAM, ACCESS=R, RESTRICT=VALUE, NAME=IDSEG,
     VALUE=DIVISION EQ 'EAST' OR 'WEST',$
     VALUE=OR 'NORTH' OR 'SOUTH',$

Note: The second and subsequent lines of a value restriction must begin with the keyword OR.

You can apply the test conditions to the parent segments of the data segments on which the tests are applicable. Consider the following example:

USER=DICK, ACCESS=R, RESTRICT=VALUE, NAME=IDSEG,
     VALUE=DIVISION EQ 'EAST' OR 'WEST',$
     NAME=IDSEG,
     VALUE=SALARY LE 10000,$

The field named SALARY is actually part of a segment named COMPSEG. Since the test is specified with NAME=IDSEG, the test is made effective for requests on its parent, IDSEG. In this case, the request PRINT FULLNAME would only print the full names of people who meet this test, that is, whose salary is less than or equal to $10,000, even though the test is performed on a field that is part of a descendant segment of IDSEG. If, however, the test was made effective on COMPSEG, that is, NAME=COMPSEG, then the full name of everyone in the data source could be retrieved, but with the salary information of only those meeting the test condition.


Top of page

x
Restricting Values a User Can Write

How to:

If a user's access rights are either W or U, VALUE tests used with the MODIFY command validate new transactions. The format of the test conditions are those used in the ON MATCH VALIDATE expressions of the MODIFY command, which is discussed in the Maintaining Databases manual.

There are two different ways you can restrict the values a user can write to a data source: by restricting the values the user actually is allowed to enter (global validate), or by restricting the values that the user is allowed to change (ON MATCH VALIDATE). You must supply an ACCESS=R restriction to restrict the user from seeing certain data values in the data source.

The simplest type of write restriction is one that prevents the user from entering certain values. Thus, it can be used to enforce editing restrictions. For instance, you use this type of restriction to prevent MODIFY users from entering nonsensical values, such as a salary of $10. You can also use this type of restriction to restrict the key values a user is allowed to enter.



x
Syntax: How to Restrict Values a User Can Write
...ACCESS=W, RESTRICT=VALUE, NAME=name, VALUE=test,$

where:

name

Is an arbitrary value used as the validate field name.

test

Is the test being performed.

This type of value test does not require data source values, therefore, you can supply an arbitrary name for the NAME attribute. The expressions are based entirely on transaction values and can be applied to the transaction immediately after reading it.



x
Syntax: How to Restrict Values a User Can Enter in a Segment

If your MODIFY procedure contains MATCH commands, restrict the values a user can enter on a segment level by supplying a segment name for NAME=. This creates a condition similar to an ON MATCH VALIDATE phrase.

...ACCESS=W, RESTRICT=VALUE, NAME=name, VALUE=test,$

where:

name

Is the name of the segment on which you perform the test.

test

Is the test being performed.



Example: Restricting Values a User Can Write

This example prevents Chuck from entering a salary that is greater than 20,000 or less than 5000. If you use an arbitrary value for NAME=, as shown above, you have created a global restriction similar to the VALIDATE command in MODIFY.

(A) USER=CHUCK ,ACCESS=W ,RESTRICT=VALUE ,
         NAME=CHRANGE,
         VALUE=SALARY LT 20000 AND SALARY GT 5000,$
(B) USER=CHUCK ,ACCESS=W ,RESTRICT=VALUE ,NAME=COMPSEG,
         VALUE=SALARY LT 20000 AND SALARY GT 5000,$

The difference between the restriction created in example B and that created by example A has to do with your MODIFY procedures. The conditions in the global restriction created by example A are applied prior to MATCH logic in the MODIFY request. The conditions created by example B are applied after your first ON MATCH condition for COMPSEG right before the action (UPDATE or DELETE) and can reference D. fields.


Top of page

x
Restricting Values a User Can Alter

How to:

You can also restrict the values a user with ACCESS=W can alter. This type of restriction is dependent on the values that are currently in the data source and prevents the user from changing certain records. The user will be allowed to perform actions only on the records that pass the validation test.



x
Syntax: How to Restrict Values a User Can Alter

The syntax of this type of value test is

...ACCESS=W, RESTRICT=VALUE, NAME=name, VALUE=test,$

where:

name

Is the name of the segment on which you perform the test.

test

Is the test being performed.



Example: Restricting Values a User Can Alter
USER=CHUCK ,ACCESS=U ,RESTRICT=VALUE ,NAME=IDSEG,
     VALUE=D.DIVISION EQ 'EAST' ,$

The prefix D. in front of the field DIVISION signals the use of the data source value of DIVISION. In this case, user Chuck can only change records of people who are in the EAST division. If, instead, you use

VALUE=DIVISION EQ 'EAST'

for the value test, Chuck will be able to change any record he wants, but the only value acceptable for the DIVISION field is EAST.

The segment name on which the test is to be applied is given as the NAME parameter. If a request statement does not perform any action on this segment, the test itself is not performed. This is true even if you are making changes to a segment that is a child of the segment on which the test is performed.

The VALUE tests are added to any VALIDATE conditions that the MODIFY request contains. Only transactions passing both the VALIDATE and VALUE tests are accepted for processing.


Top of page

x
Restricting Both Read and Write Values

In many cases it proves useful to issue both ACCESS=W (for MODIFY) and ACCESS=R (for TABLE) value restrictions for a user. This limits the values a user can write to the data source and limits the data values that the user can actually see. Do this by issuing a RESTRICT=VALUE attribute with ACCESS=R to prohibit the user from seeing any values other than those specified in the test condition. You then issue a RESTRICT=VALUE attribute with ACCESS=W that specifies the write restrictions placed on the user. You cannot use ACCESS=RW to do this.



Example: Restricting Both Read and Write Values for a User
USER=TILLY ,ACCESS=R ,RESTRICT=VALUE ,NAME=IDSEG,
     VALUE=DIVISION EQ 'NORTH',$
            ACCESS=W ,RESTRICT=VALUE ,NAME=DIVTEST,
     VALUE=DIVISION EQ 'NORTH',$

Note: HLI requires ACCESS=RW.


Information Builders