29
Fri, Nov
0 New Articles

We Interrupt This Program...

CL
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

Stopping programs at mid-execution to let the user decide what to do is, in many cases, the only way to code your program. With the Prompt User (PMTUSR) command presented here, this activity doesn’t have to imply creating dozens of display files and additional CL programs that will clutter your libraries.

You know how it is. Your users need an interactive program to display information from the sales database, but sometimes the database is not available for their use. This situation forces you to write additional code; for instance, you’ll need something to interrupt the program and ask the user what he wants to do if his request cannot be honored. Soon, your libraries are cluttered with little display files that can be used in one program only—hardly the kind of scenario you’d like when DASD is at a premium.

Not only that, but the CL program from which you need to prompt the user may already use a file of its own; in that case, you simply cannot use a second file for display purposes, because CL supports only one file. In such a case, you’d have to create another CL program to drive the display file, adding complexity upon complexity. The Prompt User (PMTUSR) command presented here takes care of all these problems.

PMTUSR is a utility command that allows you to present ad hoc panels on the screen. You don’t need to predefine anything, since you supply the text to be shown, the title of the panel, the instructions, and so on—even what input options are available and which function keys are considered valid. Figure 1 shows a sample of what PMTUSR can do.

To see how PMTUSR is implemented, take a look at a stripped-down version of the sales database inquiry program shown in Figure 2. As you can see, I’ve coded a check for the database existence with a Check Object (CHKOBJ) command; if the check fails, the CL program gets escape message CPF9801, which triggers the PMTUSR command and the rest of the code within the DO/ENDDO block.

The PMTUSR command (all source code for programs and files described in this article can be found at www.midrange computing.com/mc/99/01) supplies everything via parameters:

• TITLE provides the title at the top of the screen—in high intensity and centered. You can supply up to 50 characters.

• INSTR tells PMTUSR what kind of instructions to present. Special value *STD (standard) means “Type option, press Enter” if the prompt is input capable, or “Please read, press Enter” otherwise.

• TEXT is for you to supply up to 12 lines of text, each with a maximum of 60 characters, to tell users whatever they need to know about the interruption.

• INPUT decides whether to allow input (*YES), forbid it (*NO), or require it (*RQD).

• CAPTION provides a caption for the input field. The caption can have a maximum of 50 characters.

• VALUES lists the values the user can enter in the input field. You can supply up to 12 one-byte values; the special value *ANY means “any value is valid.”

• RTNINPUT provides the input field’s value as a return value in a CL variable that your CL program can use. So if the user types in an X in the input field and presses Enter, the variable named in RTNINPUT will have a value of X.

• FKEYS decides which function keys are allowed. *STD enables function keys F3 and F12 so that users can press either one at their terminals; *F3 enables function key F3 only; *F12 enables function key F12 only; and *NONE disables both.

• RTNFKEY provides a returned value of ENTER (if the user pressed Enter), F3, or F12, matching the function key the user pressed.

• BEEP decides whether to sound the display station’s alarm the first time the prompt is presented. If the user makes a mistake (pressing an invalid key or entering an invalid input value), PMTUSR won’t sound the alarm a second time.

In Figure 2, you’ll see that I have coded the CL program so that it gives PMTUSR everything it needs to show the prompt panel illustrated in Figure 1. When PMTUSR ends and control comes back to the CL program, &RTNFKEY can tell you whether the user pressed F3, F12, or Enter, and &RTNINPUT can tell you which option the user selected. The CL program can then take appropriate action.

Its Workings, Revealed

The display file I use, USR007DF, has a few small tricks you should know about so that you can employ them in your own display files.

First, both the INPUT and NOINPUT records put information on the screen on lines that fall among those already written by the PROMPT record format. In fact, PROMPT writes to line 1 as well as 23, and yet INPUT needs to write to lines 19 and 20. Since I want to show both record formats together, I need to overlay the records, but DDS’s OVERLAY keyword won’t work in this case; I have to use CLRL(*NO), which instructs the workstation controller not to clear any lines when writing INPUT (or NOINPUT) on the screen.

Second, I wanted the cursor in a specific place on the screen when writing NOINPUT. I could have used the CSRLOC keyword, but there’s a simpler method—creating an input field and using DSPATR(PC) to position the cursor there. In addition, I included DSPATR(PR) so the input field is protected; the net effect is that the cursor is placed in an input field, but no input is allowed.

Third and last, I provided a message subfile. This technique requires two record formats, as all subfiles do. The data record (MSGRCD) needs the SFLMSGRCD keyword to indicate on which line the messages are to appear. It also needs SFLMSGKEY and SFLPGMQ, both of which require a field name but no definition (i.e., no specification for length or data type). The control record (MSGCTL), however, must use SFLDSP, SFLDSPCTL, SFLINZ, and SFLEND; it also requires SFLSIZ and SFLPAG—the way all subfiles do—and a repeat of the SFLPGMQ keyword. Also, you must initialize the field attached to SFLPGMQ so it contains the name of your program—USR007CL, in this case.

The CL program, USR007CL, is PMTUSR’s command processing program (CPP). I won’t explain it all, but a few points are worth mentioning. At the beginning of USR007CL, I use a centering algorithm. I wanted the title, supplied to the command, to appear centered within the 50-byte output field on the display file. For example, if the title I supply consists of the word Error alone, that’s five characters out of 50. Without a centered title, the prompt panel would look odd indeed.

To center the title, I resorted to a trick made possible by the command definition. The TITLE parameter is defined as having a maximum length of 50, but it also includes VARY(*YES *INT2) in the PARM statement; this makes the parameter of varying length, and the actual length is supplied in a 2-byte header, making the title 52 bytes long. When the CPP receives the TITLE parameter, it finds the actual length by extracting the first two bytes with the %BIN built-in function, assigning that value to decimal variable &TITLELEN.

Now, all that’s left is to put some spaces before the title to make it look centered. I subtract the title length from 50 to find out how many unused positions are in the title and then divide that by 2, yielding &NBRBLANK, the number of blanks I need to place before the title. To compose the title then, I use &NBRBLANK bytes from a field named &BLANKS (50 bytes, containing blanks only) and then concatenate the title text, which begins at the third byte of the TITLE parameter value. Voilà!

One important aspect of using a message subfile is that, it’s your responsibility to clear it after each use. The easiest way to do so is to manually remove all messages from the current program’s message queue, using the Remove Message (RMVMSG) command, immediately after each user input operation. This RMVMSG appears right below the Send Receive File (SNDRCVF) command, which is to CL what the Execute format (EXFMT) command is to RPG.

Yet More Tricks

PMTUSR is pretty tricky, but that’s nothing compared with the tricks you can do with it. So far, I have shown you how to use it to interrupt a program and ask the user a simple question. But you can use it for other things, too. For example, you can use PMTUSR to display a menu, one that’s built on the fly and processed immediately in the same CL program. You can even retrieve the options from a database file, making your menu rather dynamic. Of course, the limitation is that it display and recognize only 12 options (one per line, one per valid input value).

I feel that PMTUSR is quite useful, something you’ll want to have in your ever- fattening bag of tricks.

Reference AS/400 CL Programming (SC41-5721-01, CD-ROM QB3AUO01)

Figure 1: Typical output produced by PMTUSR

PGM

DCL VAR(&RTNINPUT) TYPE(*CHAR) LEN(1)

DCL VAR(&RTNFKEY) TYPE(*CHAR) LEN(5)

/* Check existence of sales database */
AGAIN:

CHKOBJ OBJ(SALESDB) OBJTYPE(*FILE)

MONMSG MSGID(CPF9801) EXEC(DO)

/* If not found, prompt user */

PMTUSR TITLE('Sales Database Not Available') +

INSTR(*STD) TEXT('The Sales Database is +

not available at this time.' 'Please do +

one of the following:' ' ' 'A. Alert +

QSYSOPR' 'T. Try again' 'C. Cancel') +

INPUT(*RQD) CAPTION('Enter your option +

here:') VALUES(A T C) RTNINPUT(&RTNINPUT) +

FKEYS(*STD) RTNFKEY(&RTNFKEY) BEEP(*YES)

/* Cancel request if F3 or F12 pressed */

IF COND(&RTNFKEY *EQ 'F3' *OR &RTNFKEY *EQ +

'F12') THEN(GOTO CMDLBL(CANCEL))

/* Enter pressed; check user input */

ELSE CMD(DO)

/* User selected to alert QSYSOPR */

IF COND(&RTNINPUT *EQ 'A') THEN(DO)

SNDMSG MSG('Sales Database not available') +

TOMSGQ(QSYSOPR)

GOTO CMDLBL(CANCEL)

ENDDO

/* User selected to try again */

ELSE CMD(IF COND(&RTNINPUT *EQ 'T') THEN(DO))

GOTO CMDLBL(AGAIN)

ENDDO

/* User selected to cancel */

ELSE CMD(DO)

GOTO CMDLBL(CANCEL)

ENDDO

ENDDO

ENDDO

/* Process sales database */

RETURN

/* Cancel sales database request */
CANCEL:

SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Sales +

database request not honored; database +

not available') MSGTYPE(*ESCAPE)

ENDPGM

Figure 2: This program illustrates use of the PMTUSR command

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More 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.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY 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.

  • SB HelpSystems ROBOT GenericForms 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.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA 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:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA 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.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra 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: