| The API Corner: Accessing a Command Line |
 |
 |
 |
| Programming - APIs | |||||||||||||||
| Written by Bruce Vining | |||||||||||||||
| Wednesday, 18 April 2012 00:00 | |||||||||||||||
|
The Display Command Line Window (QUSCMDLN) API makes it easy!
When recently visiting a client, I overheard one of their developers mention the desire to get to a command line from within an application program. There is, of course, an API to do just that. And, as the API has been around since V1R3, I suspect there are quite a few developers who have had a similar need.
The Display Command Line Window (QUSCMDLN) API, documented here, is not the easiest to find as it's located in the User Interface Manager (UIM) category of system APIs, but it is certainly one of the easiest APIs to use. I say this, in regard to ease of use, as there are no parameters at all associated with the API—not even the traditional API Error Code parameter. You simply call the API QUSCMDLN.
Let's say you have an existing application, named DSPHI (Display Hi), using the display file (*DSPF) HI. Below is the DDS source for the HI *DSPF, followed by the RPG source for DSPHI.
A R HITHERE A CF03(03 'Exit') A 2 2USER A 2 34'Sample Screen' A 2 69DATE(*YY) A EDTCDE(Y) A 10 39'Hi' A 23 2'F3=Exit' A COLOR(BLU)
fHI cf e workstn
/free
exfmt HiThere; dow (not *in03); exfmt HiThere; enddo;
*inlr = *on; return;
/end-free
The DSPHI program, as you can see, is quite simple. It displays record format HITHERE, which essentially shows the word "Hi," within a do while loop that is ended when command key 3 is used. Assuming the DDS source is in source file QDDSSRC and member HI, you can create the *DSPF using the command CRTDSPF FILE(HI) SRCFILE(QDDSSRC). Assuming the RPG source is in source file QRPGLESRC and member DSPHI, you can create the *PGM using the command CRTBNDRPG PGM(DSPHI). To run the program, use the command CALL DSPHI.
Supporting command line access within the DSPHI program, using the QUSCMDLN API, requires only minor changes, which are shown bolded below.
A R HITHERE A CF03(03 'Exit') A CF09(09 'Cmd line') A 2 2USER A 2 34'Sample Screen' A 2 69DATE(*YY) A EDTCDE(Y) A 10 39'Hi' A 23 2'F3=Exit' A COLOR(BLU) A 23 15'F9=Run command' A COLOR(BLU)
fHI cf e workstn
dUseCmdLine pr extpgm('QUSCMDLN')
/free
exfmt HiThere; dow (not *in03); if *in09; UseCmdLine(); endif; exfmt HiThere; enddo;
*inlr = *on; return;
/end-free
The changes to the HI *DSPF are to enable command key 9 and to display to the user that F9 is available if the user wants to run a command. The changes to the DSPHI *PGM are simply to test if F9 has been pressed and, if so, to call the QUSCMDLN API. The API itself is prototyped using the name UseCmdLine. With these rather modest changes, the user can now get to a command line window using F9. From the window shown by the QUSCMDLN API, the user can enter commands, prompt commands, retrieve previous commands, and return to the DSPHI program by using F12. The window itself will be displayed using lines 18 through 24.
Roughly two seconds after implementing this change to the DSPHI program, or even before you make the change, it may occur to you that not all users should be able to get to the command line so easily. To disable F9 on the HITHERE record format is simple enough. Use a conditioning indicator, such as *in39 shown below in bold, to disable both the command key and the F9 prompt.
A R HITHERE A CF03(03 'Exit') A 39 CF09(09 'Cmd line') A 2 2USER A 2 34'Sample Screen' A 2 69DATE(*YY) A EDTCDE(Y) A 10 39'Hi' A 23 2'F3=Exit' A COLOR(BLU) A 39 23 15'F9=Run command' A COLOR(BLU)
The more difficult decision is how to determine if indicator 39 should be on (enabling the command line window) or off (disabling the command line window). There are many possible solutions to this question. One solution, naturally using an API, is to decide that end users should not have access to the command line from DSPHI while everyone else should be allowed access.
Every user profile on the system has a user class (USRCLS) attribute associated with it. This attribute can have one of several values; these values include *USER (the default), *SYSOPR, *PGMR, *SECADM, and *SECOFR. So the question becomes "How do I access the user class of the user profile currently running the DSPHI program?" For this, we will turn to the Retrieve User Information (QSYRUSRI) API documented here.
The QSYRUSRI API, available since V2R2, is admittedly more complex to use than the QUSCMDLN API. The Retrieve User Information API has five parameters, which certainly exceeds the number of parameters defined for QUSCMDLN (which is zero). Incorporating QSYRUSRI into the DSPHI program, though, is still very straightforward.
QSYRUSRI is a traditional retrieve API. The five parameters that are defined represent the receiver variable, the length of receiver variable, the format of receiver variable, the user profile to access, and the standard API error code parameter, respectively. If you need a refresher on these standard API parameters, you can refer to my previous articles "Understanding API Data Types" and "Retrieving Information, Part I."
The third API parameter, Format name, supports the specification of one of three formats. Format USRI0100 returns sign-on and password-related information, format USRI0200 authority information, and format USRI0300 all user information. For the DSPHI application, we'll be using format USRI0200 as it provides the user class attribute of the user profile. RPG definitions for all three of these formats can be found in member QSYRUSRI of source file QSYSINC/QRPGLESRC. We will be using these IBM provided definitions in our DSPHI program. If you currently do not have the library QSYSINC on your system, it is installed as part of option 13 of the operating system.
The fourth parameter, User profile name, supports the special value *CURRENT, indicating that we want information related to the user profile currently running the program.
Below, shown in bold, are the changes necessary to the DSPHI application in order to either disable or enable F9 based on the current user being of class *USER or not.
fHI cf e workstn
dChkUsr pr extpgm('QSYRUSRI') d RcvVar 4096 options(*varsize) d LenRcvVar 10i 0 const d Format 8 const d UsrPrf 10 const d QUSEC likeds(QUSEC)
dUseCmdLine pr extpgm('QUSCMDLN')
/copy qsysinc/qrpglesrc,qusec /copy qsysinc/qrpglesrc,qsyrusri
/free
QUSBPrv = 0; ChkUsr(QSYI0200 :%size(QSYI0200) :'USRI0200' :'*CURRENT' :QUSEC); *in39 = (QSYUC <> '*USER');
exfmt HiThere; dow (not *in03); if *in09; UseCmdLine(); endif; exfmt HiThere; enddo;
*inlr = *on; return;
/end-free
The changes are to do the following:
DSPHI will, with these minor changes, now enable or disable the F9 command key based on the user class of the current user. The variable being examined, QSYUC (User Class), is defined as shown below in the QSYSINC definition of format USRI0200.
DQSYI0200 DS D* Qsy USRI0200 D QSYBRTN01 1 4B 0 D* Bytes Returned D QSYBAVL01 5 8B 0 D* Bytes Available D QSYUP02 9 18 D* User Profile D QSYUC 19 28 D* User Class
Next month, we'll look at another possible solution of how to determine if F9 should be enabled or disabled for a given user. This alternative solution will be significantly more flexible than today's approach of basing our decision on the user class of the current user, though it will also involve quite a few more APIs.
As usual, if you have any API questions, send them to me at bvining@brucevining.com. I'll see what I can do about answering your burning questions in future columns.
| |||||||||||||||
|
|||||||||||||||
| Last Updated on Wednesday, 18 April 2012 00:00 | |||||||||||||||
You must be logged in to view or make comments on this article