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:
- Prototype the QSYRUSRI API using the name ChkUsr
- /Copy the SYSINC-provided definitions of the API error code parameter (member QUSEC) and the QSYRUSRI API formats (member QSYRUSRI)
- Set the API error code Bytes provided field (QUSBPrv) to 0 so that any errors are returned as escape messages
- Call the QSYRUSRI API asking for format USRI0200 information related to the current user
- Turn on indicator 39 if the current user's user class (QSYUC) is not *USER
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
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online