05
Tue, Nov
5 New Articles

TechTalk August 1998

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

QSYSINC—Your API Example Library

If you’ve written applications that use OS/400 APIs, you know what a chore it can be to figure out what some of the parameters are and how they are used. The API Reference manual is not very helpful either since it assumes you already understand what it’s referring to. However, help is available. The system library QSYSINC contains source include files you can copy into your RPG, COBOL, or C programs. These source include files contain source examples of the various data structures required by the APIs, written in the various languages for many of the APIs in the API Reference manual. The naming conventions for the source include files are the same as either the OPM API or the ILE service program name. If the API has a callable and a bindable interface, a source include file exists with both names.

The QSYSINC library is provided to you free with every copy of OS/400, but you need to install it by loading your OS/400 install media in the appropriate drive and typing GO LICPGM on a command line. You’ll need to be signed on as QSECOFR or with a user profile that has *SECOFR *ALLOBJ special authorities. From the Licensed Programs menu, select option 11, Work with Licensed Programs. On the next panel, select the option OS/400—Openness Includes. This option contains the QSYSINC library.

The table in Figure 1 lists the API source include files that are shipped with the QSYSINC library.

— Shannon O’Donnell Technical Editor Midrange Computing

Go to the Web to Understand PC File Formats

For years, AS/400 programmers have had to deal with only one filing system—DB2/400. Now that the AS/400 is connecting to every machine imaginable and has an Integrated File System (IFS), you may have to work with files of other formats. Fortunately, there is plenty of help for you on the World Wide Web.

A good place to start is at the People Helping One Another Know Stuff (PHOAKS) site at http://www.phoaks.com/. (You’ll find plenty of information about all sorts of topics, not just computers.) Another good place to try is Val Mushinskiy’s Web site (http://www.geocities.com/~vmushinskiy/fformats/fformats.htm).

So the next time your boss asks if you can make your RPG program create a file in dBASE III format in the IFS, tell him, “Certainly!”

— Robert Clark Plexsys Inc.

Rereading Files in CL

As a rule, a CL program can read a database file only once. After the Receive File (RCVF) command finds the end of the file, there is no way to reset the file pointer and read the file again. There is a way to reread a database file in a CL program, however. Here is what you must do:

1. Use the Number of current records (NBRCURRCD) parameter of the Retrieve Member Description (RTVMBRDR) command to determine the number of active records in the member.

2. Override the database file to SHARE(*YES). This establishes an open data path (ODP) and allows the Position Database File (POSDBF) command to function properly.

3. Use the Open Database File (OPNDBF) to establish a file ID link that can be referenced by POSDBF.

4. Count the records as you process them.
5. When the record counter matches the number of active records, you have processed the last record. Use the POSDBF command to reset the file pointer to the first record.

The short CL program in Figure 2 illustrates this technique. Be aware that this technique won’t work correctly if other jobs are adding records to the file, or deleting records from the file, at the same time.

— Tom Conover Warner/Chappell Music, Inc.

You Can Personalize Messages

The Override with Message File (OVRMSGF) command may be used to customize the messages you and your users see. OVRMSGF works differently from other types of file overrides. Other override commands, such as Override with Database File (OVRDBF), tell the system to use one file instead of another. OVRMSGF tells the system to give precedence to the overriding message file but to resort to the overridden file if necessary. That is, if a message ID is found in a message file I have created, the system will use that message. Otherwise, it will look for the message ID in IBM’s message file.

To use your own custom messages, do the following:
1. Create a message file in your test library.
2. Use the Merge Message File (MRGMSGF) command to duplicate the messages you wish to customize.

3. Use the Work with Message File (WRKMSGF) command to modify the message file in your test library. Do not modify IBM’s message files.

You need to run OVRMSGF in any job you want to customize. My initial program includes the code shown in Figure 3. The overrides remain in effect for the duration of the job because my initial program stays in the call stack until I sign off.

4. Figure 4 contains a list of some of my custom message texts. Most of them are humorous changes I have made to lighten my day. Others, like CPD8061, give me more information than, or different information from, the versions IBM supplies.

The second-level message text of CPX2423 contains the heading seen on the command entry display. I changed this to my personal slogan, “Better living through fine code and hot coffee!”

The message text for CPX2313 should look familiar to you. These are the commands executed from the system request menu. I usually modify the DSPJOB to WRKJOB—which gives me a command line from almost anywhere. You may prefer to change DPSJOB to WRKJOB instead.

5. Figure 5 contains one-time sample code you can use to build your custom message file from frequently used original messages.

— Jerry Jewel This email address is being protected from spambots. You need JavaScript enabled to view it.

Use Your PC to Shop for an AS/400

Q: My company is looking into buying a new AS/400. Is there a good Web site that explains all of the possible options and features for the system? I’m looking for something that describes in detail what comes with IBM’s different value paks and which software is actually included with the base product. The IBM sites seem to confuse the process rather than simplify it.

— Dave Sommerville This email address is being protected from spambots. You need JavaScript enabled to view it.

A: Try http://www.as400.ibm.com/oee/config.htm. You can download a program called PCAS400, which will configure and price all the hardware and software IBM has available for the AS/400 market.

— Jack McGuigan MIS Manager American Life Ins. Co

Common Calculations Make Good Subprocedures

If you still haven’t started writing RPG IV subprocedures, you’re missing a great feature of the new RPG, but maybe you’re just not sure where to begin.

I began by looking for common business processes. Every organization has them. They’re calculations that you find over and over in programs. When you modify one of these routines, you end up having to change 50 programs.

For example, suppose several programs calculate a gross profit margin. You could start your adventure into subprocedures by creating a service program with one subprocedure. You’ll need a function prototype (see Figure 6) that can be copied into both the service program source and into the source of the programs that use the function. You’ll also need to write the subprocedure, as in Figure 7. To use the subprocedure, use code like that in Figure 8. As you identify more common routines, add them to the service program.

If you’ve put off using subprocedures, now you know where to begin. Get out those back issues of Midrange Computing, read about subprocedures, and have at it!

— Paul Sgroi System One Solutions, Inc. Senior Programmer/Analyst

What’s NOOPT About?

Q: I’ve read what the manual has to say about the NOOPT keyword in RPG IV, but it’s still not clear to me why or when you would use it. Can you shed some light on this?

— John V. Thompson Honda New Zealand This email address is being protected from spambots. You need JavaScript enabled to view it.

A: Optimization by the compiler may mean that, at runtime, some values are stored in registers and restored to your program storage only at predefined points during normal program execution. Exception handling may break this normal execution sequence, and, consequently, program variables contained in registers may not be returned to their assigned storage locations. NOOPT ensures that the content of the associated data item always contains the latest value.

The ILE RPG Reference (SC09-2508, CD-ROM QB3AGZ00, section 3.4.2.22) states, “Any data item defined in an OPM RPG/400 program is implicitly defined with NOOPT. So, if you are creating a prototype for an OPM program, you should specify NOOPT for all parameters defined within the prototype. This will avoid errors for any users of the prototype.”

From this, I take it that, unless the called program expects the “optimized” behavior, there may be circumstances in which you have problems. Unless you can be sure of the implementation details of both called and caller programs and are prepared to delve into the intricacies of code optimization, it seems to me that the only way you can be sure the interface is bulletproof is to specify NOOPT. Because you usually put prototype definitions in copybooks, you want only one version of a prototype anyway—presumably the version that will work in all circumstances.

I don’t have any information about QMHSNDPM other than the published interface and the fact that it is an OPM program. I sleep better at night knowing that the interface definition I’m using will continue to work no matter what clever optimization is used or how QMHSNDPM does or does not behave.

I don’t usually use NOOPT on bound calls to the ILE APIs (like CEE*). These ILE APIs presumably have been designed for an ILE environment, so I don’t usually bother. I’m not sure if this is sensible or not, but I haven’t had any problems so far.

The other place you need to specify NOOPT is on fields referenced in any exception handling code (like PSSR and condition handlers).

— Derek Butland

A: Say you have a NOOPT variable that you want to pass by address to an OPM program. The compiler won’t allow it if the parameter isn’t defined as NOOPT, so by coding NOOPT on all OPM program calls, you avoid this potential problem. The code in Figure 9 illustrates the problem. The RPG IV compiler will generate error *RNF5423 (the NOOPT variable cannot be passed by reference to a parameter that did not specify NOOPT). Coding NOOPT on the prototype doesn’t actually cause any different code to be generated for calls.

— Barbara Morris IBM Toronto RPG Compiler Development

Use MAPVAL to Eliminate Date Confusion

The V4R2 Mapped Value (MAPVAL) keyword in DDS allows you to map a given value to another for display purposes. You could, for instance, specify that 01/01/0001 should display as *BLANK. Upon input to the program, workstation data management would convert the blank field back to 01/01/0001. Figure 10 illustrates how to use MAPVAL.

— Bruce Vining IBM Rochester

Define Your Own Data Types in ILE COBOL

It’s fairly common to want to duplicate all the elementary and group items below a base item and place them under a new base item. For example, in Figure 11, I have duplicated elem1 and elem2. Now, I have to remember to change both copies of elem1 if I change elem1 (and similarly for elem2). Of course, some people use COPY libraries to get around this problem, but, in complicated scenarios, you could end up with many COPY statements.

The TYPEDEF reserved word in V4R2 ILE COBOL allows us to define templates that can be used by both mygroup1 and mygroup2.

In Figure 12, both mygroup1 and mygroup2 end up with the exact same definition as before. However, if I want to change the way elem1 is defined, I have to do it only once.

TYPEDEF can even be used with data defined with the level number 77, which normally are not divided into subordinate elementary items. Variable mygroup3, like mygroup1 and mygroup2, also has data elements elem1 and elem2.

— Chris Tandy IBM Toronto

Update Data Through a Join

Q: I would like to use interactive SQL to update columns in one table with values from another table. For example, if I have customer and ZIP code tables, as in Figure 13, can I set CustCity equal to ZpCity where CustZip is equal to ZpCode?

— Jake Lee shih_lee@kingston

A: Few versions of SQL will allow you to update through a join. SQL/400 is no exception.

If you have a version of SQL that executes from a CL program, such as EXCSQLSTM (presented in “The EXCSQLSTM Utility,” MC, December 1994), you can use another method to carry out the update. I have done this numerous times. It is a somewhat simple but slow process.

Declare the file with the reference information (the file not being updated) in a CL program. Write a loop to read each record of the file. Inside the loop, put an update statement that includes the CL variables substituted into the proper places of the SQL statement. See Figure 14 for an example that solves your request.

— Bill Robins This email address is being protected from spambots. You need JavaScript enabled to view it.




Figure 1: Source include files in QSYSINC


PGM DCL VAR(&COUNT) TYPE(*DEC) LEN(10)
DCL VAR(&NBRCURRCD) TYPE(*DEC) LEN(10)

DCLF FILE(MYFILE)
RTVMBRD FILE(MYFILE) NBRCURRCD(&NBRCURRCD)
OVRDBF FILE(MYFILE) SHARE(*YES)
OPNDBF FILE(MYFILE) OPTION(*INP)

LOOP:

RCVF

MONMSG MSGID(CPF0864) EXEC(GOTO CMDLBL(END_LOOP))

/* Process record here */

SNDUSRMSG MSG(&MYFILE) MSGTYPE(*INFO) TOUSR(*REQUESTER)
CHGVAR VAR(&COUNT) VALUE(&COUNT + 1)
IF COND(&COUNT *EQ &NBRCURRCD) THEN(DO)
/* End of File has been reached for the first time */

POSDBF OPNID(MYFILE) POSITION(*START)

ENDDO

GOTO LOOP

END_LOOP:

CLOF OPNID(MYFILE)
DLTOVR FILE(MYFILE)
ENDPGM

Figure 2: This CL program reads a database file twice

CHKOBJ OBJ(JEWEL/JEWEL) OBJTYPE(*MSGF)

MONMSG MSGID(CPF9801) EXEC(GOTO CMDLBL(SKIP1))
OVRMSGF MSGF(QCPFMSG) TOMSGF(JEWEL/JEWEL)
OVRMSGF MSGF(QEDTMSG) TOMSGF(JEWEL/JEWEL)
OVRMSGF MSGF(QUOMSGF) TOMSGF(JEWEL/JEWEL)



Tech_Talk406-00.png 750x600

SKIP1:

Figure 3: Overriding message files


 Figure 4: Customized messages


PGM PARM(&MSGF)

DCL VAR(&MSGF) TYPE(*CHAR) LEN(10)

/* Create message file in *CURRENT library */

CRTMSGF MSGF(*CURLIB/&MSGF) TEXT(‘Custom messages’)

/* Copy the original messages */

/* In the SELECT parameter, list the IDs */

/* of the messages you want to modify */

MRGMSGF FROMMSGF(QSYS/QCPFMSG) TOMSGF(&MSGF) +
SELECT(CPC8061 CPF9897 CPF9898 CPI3405 +

CPX2313 CPX2423)

MRGMSGF FROMMSGF(QPDA/QEDTMSG) TOMSGF(&MSGF) +
SELECT(EDT0229 EDT0601 EDT1513 EDT1618 +

EDT1619)

MRGMSGF FROMMSGF(QPDA/QUOMSGF) TOMSGF(&MSGF) +

SELECT(PDM0018)

WRKMSGF MSGF(*CURLIB/&MSGF)

ENDPGM

Figure 5: Use this one-time CL program to build a custom message file

D GROSSMARGN PR 5P 2

D 9P 2 VALUE

D 9P 2 VALUE





Tech_Talk407-00.png 750x600

Figure 6: The financial calculations prototypes member, FINCALXCPY

*=========================================================

* To compile:

*

* CRTRPGMOD MODULE(XXX/FINCALX) SRCFILE(XXX/QRPGLESRC)

* CRTSRVPGM SRVPGM(XXX/FINCALX) EXPORT(*ALL)

*

*=========================================================

H NOMAIN FLTDIV(*YES) EXPROPTS(*RESDECPOS)

*

/COPY XXX/QRPGLESRC,FINCALXCPY

*

PGROSSMARGN B EXPORT

D PI 5P 2

D MARGNSLS 9P 2 VALUE

D MARGNCST 9P 2 VALUE

* GET THE GROSS PROFIT MARGIN...

C IF MARGNSLS *ZERO

C RETURN %DECH(

C (((MARGNSLS - MARGNCST)/MARGNSLS)*100)

C : 5 : 2)

C ELSE

C RETURN *ZERO

C ENDIF

PGROSSMARGN E

Figure 7: The financial calculations service program source member, FINCALX

*============================================================

* To compile:

*

* CRTRPGMOD MODULE(XXX/FINCALXTST) SRCFILE(XXX/QRPGLESRC)

* CRTPGM PGM(XXX/FINCALXTST) BNDSRVPGM(XXX/FINCALX)

*

*============================================================

*

/COPY XXX/QRPGLESRC,FINCALXCPY

*

D SALES S 9P 2 INZ(10.00)

D COST S 9P 2 INZ( 5.00)

D MARGIN S 5P 2 INZ(*ZEROS)

*

C EVAL MARGIN = GROSSMARGN(SALES:COST)

*

C EVAL *INLR = *ON

Figure 8: Once the subprocedure is compiled and working, begin to retrofit it into your programs

D fld s 10a noopt

D proc pr

D parm 10a

C callp proc(fld)

Figure 9: Incorrect use of NOOPT

A R FMT01
A 6 5’DATE:’
A ADATE L B + 1DATFMT(*USA)
A MAPVAL((‘01/01/0001’ *BLANK))

Figure 10: MAPVAL converts dates, times, and time stamps from one value to another

01 mygroup1.

05 elem1 PIC X .

05 elem2 PIC s9.

01 mygroup2.

05 elem1 PIC X .

05 elem2 PIC s9.

Figure 11: These two group items are defined with the same elementary items

DATA DIVISION.

WORKING-STORAGE SECTION.
01 mytemplate IS TYPEDEF.

05 elem1 PIC X.

05 elem2 PIC S9.

01 mygroup1 TYPE mytemplate.
01 mygroup2 TYPE mytemplate.
77 mygroup3 TYPE mytemplate.

PROCEDURE DIVISION.
MAIN-LOGIC.

MOVE “B” TO elem1 OF mygroup1.

MOVE “C” TO elem1 OF mygroup2.

MOVE “D” TO elem1 OF mygroup3.

COMPUTE elem2 OF mygroup1 = 7.

COMPUTE elem2 OF mygroup2 = 8.

COMPUTE elem2 OF mygroup3 = 9.

DISPLAY mygroup1.

DISPLAY mygroup2.

DISPLAY mygroup3.

GOBACK.

Figure 12: The TYPEDEF keyword allows group items to share common definitions

Customers ZIP Codes

CustId ZpCity CustName ZpCode CustAddr
CustCity
CustZip

Figure 13: Customer and ZIP code tables

PGM

DCLF FILE(ZIPCODES)
DCL VAR(&ZIPCHAR) TYPE(*CHAR) LEN(5)

READ:

RCVF MONMSG MSGID(CPF0864) EXEC(GOTO CMDLBL(EOF))
CHGVAR VAR(&ZIPCHAR) VALUE(&ZPCODE)
EXCSQLSTM SQLSTM(‘Update Customers set CustCity=’’’ +

*CAT &ZPCITY *CAT ‘’’ where CustZip=’ +

*CAT &ZIPCHAR)
GOTO CMDLBL(READ)

EOF:

ENDPGM

Figure 14: This CL program updates a field in one file from a field in another one

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: