IFFLS (HLI function)

From m204wiki
Jump to navigation Jump to search

The conventions used on this page are described in Function call notation conventions.

Summary

Description
The IFFLS call (FIELD LEVEL SECURITY) checks security access level to a specified field, or to all fields, in a file or group on the current thread.
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
61

Syntax

IFFLS(RETCODE,FIELD_NAME,ACCESS_SPEC,FILE_IND)

Compile-only form
Not available
Execute-only form
Not available

Specify the parameters in the syntax order shown above.

Parameter Description
RETCODE [O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value.
FIELD_NAME [I,c,o] The field name is an optional input parameter which specifies the name of the field or identifies a field name variable for a field whose security access level is to be checked.

Note: If the field name is not specified, IFFLS defaults to checking all of the fields in the indicated file or group. In this case, Model 204 returns a completion code of 0 only if the thread has the requested access to every field. Use IFFLS without specifying a field name with caution; since this requires that Model 204 examine every field, it can slow performance.

ACCESS_SPEC [I,s,o] The access specification is an optional input parameter which summarizes the needed field access. Specify a short character string which contains any of the following character codes:

S = SELECT
R = READ
U = UPDATE
A = ADD

Note: If you do not specify the access codes, the specification defaults to a value of SRUA, for all privileges.

FILE_IND [I,s,o] The file indicator is an optional input parameter which specifies the file or group context for the access check. If you do not specify the file indicator, IFFLS uses the context established by the IFOPEN call. You can specify the file indicator in one of the following ways on a single cursor IFSTRT thread:
  • If the access is to be checked for a particular file in the group, specify that file name.
  • If the access is to be checked for the file containing the current record, specify the $CURFILE string.
  • To indicate the group update file, specify the $UPDATE string.

In group context, IFFLS returns a completion code of 0 if there is a set of files in the group for which the access would be allowed.

On a multiple cursor IFSTRT thread, you can specify any file or group using the following format:

filename

Note: On a multiple cursor IFSTRT thread, $UPDATE and $CURFILE are illegal.

Usage notes

Use the IFFLS call to avoid or diagnose errors that occur because of field level security violations. You can use the IFFLS call on any type of IFSTRT thread.

Completion return code (RETCODE)

If the IFFLS call is unsuccessful, Model 204 returns an error code of 4 if any one of the following error conditions occurs:

  • The indicated access (ACCESS_SPEC) is not allowed.
  • The access string (ACCESS_SPEC) is invalid.
  • The field name (FIELD_NAME) is not defined.
  • No file or group is open.
  • The file indicator (FILE_IND) is invalid.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 FIELDNAME PIC X(7) VALUE "SALARY;". 05 ACCESS PIC X(2) VALUE "U;". . . . PROCEDURE DIVISION. . . . CALL "IFFLS" USING RETCODE, FIELDNAME, ACCESS.