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 This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll see what I can do about answering your burning questions in future columns.

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale