Not many people realize that IBM i lets you define your own ad-hoc or application-defined special authorities.
That’s not real surprising considering that neither the name of the mechanism nor the documentation says anything about special authorities.
So what mechanism is used to implement these special authorities?
IBM calls it “function usage.” The idea is to let users allow or deny the “usage” of functions (rather than objects) implemented by programs or applications.
Pretty cool, huh?
But nobody knows because “function usage” is one of the worst names for operating system capabilities that IBM has ever created!
The classic computer terminology for this sort of thing is “privilege,” and the terminology used in IBM i is “special authority.” Something based on either of these classic terms would have been good; for example, USRDFDPRV or something like it.
The person responsible for the “function usage” terminology should be shot!
Please Don’t Shoot Me!
I can say this comfortably because the terminology is 99% my fault! A small team of folks architected and implemented this capability years ago (V5R3). I was the team leader and one the principal architects. When we couldn’t think of a good name for the capability, I came up with the term “function usage.”
I won’t claim 100% responsibility only because the terminology is so bad and so awkward that someone else should have noticed!
How to Use “Function Usage”
The functionality is so much better than the name. Function Usage consists of a few commands and APIs.
The commands are:
- Check Function Usage (CHGFCNUSG)
- Display Function Usage (DSPFCNUSG)
- Work with Function Usage (WRKFCNUSG)
The APIs are:
- Change Function Usage (QSYCHGFUI)
- Check User Function Usage (QSYCKUFU)
- Deregister Function (QSYDRGFN)
- Register Function (QSYRGFN)
- Retrieve Function Information (QSYRTVFI)
- Retrieve Function Usage Information (QSYRTVFUI)
Without going into the gory details, you essentially register a “function” (or “privilege” or “special authority”) using the QSYRGFN API.
Once you register your “function” name, you can use iNav to grant or revoke your application-defined special authority to/from user and group profiles.
If you want to see the profiles to which a specific application-defined special authority has been granted or revoked, use the DSPAPPSPCA (Display Application-Defined Special Authority) command.
Check User Function Usage (QSYCKUFU) API
From a programming point of view, the Check User Function Usage (QSYCKUFU) API is of primary importance.
At the head of the block of code that performs some function for which an application-defined special authority has been registered, call this API with the user profile name and the “application-defined special authority” or “function usage ID name.”
The API returns a value of “1” if the user does not have the specified application-defined special authority, and the code performing that function is skipped. The application can determine if not having the application-defined special authority represents an error condition or merely a control point.
If the user has been granted the application-defined special authority, the API returns a value of “2” and the code performing the function associated with the privilege is executed.
Some Cool Extras
There are a couple of cool capabilities that can be defined at the time an application-defined special authority is registered.
The first is the default setting for all users on the system. You can control whether, by default, the special authority is granted to all users or revoked from all users. Then you can use the CHGFCNUSG command to grant or revoke the special authority to/from specific users and groups.
The second capability you can control at the time of registration is whether, when a “check function usage” check is performed, *ALLOBJ special authority also means that you have the specified application-defined special authority. This means that you can write a program that not even a profile with *ALLOBJ special authority can successfully execute! Keep in mind, however, that someone with *ALLOBJ special authority can grant themselves the application-defined special authority.
“Function Usage” in Action
An example of how this could be used is a bank teller application. Assume that all tellers can process cash withdrawals for any amount up to $10,000, but only a couple of tellers are allowed to process withdrawals in excess of this amount.
One way to implement this in an application is the following:
1. Create an application-defined special authority called “BANK_TELLER_LARGE_WITHDRAWALS.”
The function is registered such that by default nobody has this special authority.
2. Use the CHGFCNUSG command to grant the two authorized tellers the “BANK_TELLER_LARGE_WITHDRAWALS” special authority.
3. In the teller application code
a. Check if the withdrawal amount is greater than $9999, if so
i. Use the Check User Function Usage (QSYCKUFU) API to determine if the teller is allowed to perform large withdrawals.
1. If not, then go through the “Action Requires Approved Teller” process
2. Otherwise, process the transaction.
b. Otherwise, process the withdrawal transaction.
And there you have it — your application-defined special authority. No fuss. No muss.
