23
Sat, Nov
1 New Articles

Programmer's Toolbox

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

Two of my favorite commands in CL programs are Check Object (CHKOBJ) and Retrieve Object Description (RTVOBJD). You can do a lot with these two commands.

Even some experienced CL programmers may not fully understand these commands, so I’ll explain them. I’ll also include some of the reasons I like and dislike CHKOBJ and some of the problems programmers have with it.

The CHKOBJ command allows you to check the existence of an object, a member, or the user’s authority to an object. (Note that you must specify an object type on CHKOBJ.) For example, suppose you key in this command:

CHKOBJ OBJ(PGMA) OBJTYPE(*PGM)

If PGMA exists on the library list, the command just does a return. When the check is successful, the command completes normally and does not send any form of message. The way you find out that something went wrong is to monitor for possible escape messages, such as this one:

CHKOBJ OBJ(PGMA) OBJTYPE(*PGM)
MONMSG MSGID(CPF9801) EXEC(DO) /* Not found */
/* Your code for ‘not found’ */
ENDDO /* Not found */

There are several conditions you can monitor with CHKOBJ. The following are the most typical:

• CPF9801—The object is not found. The message is really saying that the combination of name and object type have not been found.

• CPF9802—Not authorized. This message occurs only if you have used the AUT parameter, such as in the following example:

CHKOBJ OBJ(PGMA) OBJTYPE(*PGM) AUT(*USE)

CHKOBJ

• If you do not have *USE authority, the escape message occurs. Note that if you do not use the AUT parameter, you are ensuring only that the object exists. You can use CHKOBJ on an object that you have no authorization to; however, you must be authorized to the library containing the object you are trying to check. (See the authorization error described for the CPF9820 message.)

The AUT parameter supports the simple values of *USE, *CHANGE, and *ALL. If you ask for *USE authority and actually have a greater authority to the object (such as *CHANGE), CHKOBJ completes normally. The individual authorities that make up the check you are asking for (such as *USE = *OBJOPR, *READ, and *EXECUTE) are checked rather than the word *USE.

You can also check for very specific combinations such as this one:

... AUT(*OBJOPR *READ *ADD)

• CPF9810—The library is not found. This message occurs if you used a qualified name and the library did not exist. Note the distinction between checking for a library object and checking for a qualified name. If you key in CHKOBJ OBJ(LIBA/OBJ1) OBJTYPE(*xxx) and LIBA does not exist, CPF9810 is sent. If LIBA exists, but not OBJ1, CPF9801 is sent. You can check whether a library exists by using code like this:

CHKOBJ OBJ(LIBA) OBJTYPE(*LIB)

In this case, CPF9801 occurs if the library is not found. It is when you use a qualified name for the object and the library is not found that CPF9810 occurs. Another error situation occurs when the library exists, but you are not authorized to it. See the CPF9820 message.

• CPF9815—The member does not exist. This occurs only if you specified the MBR parameter:

CHKOBJ OBJ(FILEA) OBJTYPE(*FILE) MBR(MBR1)

The escape message is telling you that the file exists, but the member does not. If the file does not exist, you get CPF9801, not CPF9815. You could specify the following instead:

CHKOBJ OBJ(FILEA) OBJTYPE(*FILE) MBR(*FIRST)

In this case, you are checking to see if there are any members in the file. If you’ve removed the first member but other members still exist, the command completes normally because there is still a “first” member. If you use an unqualified object name, the first file that the system comes to on the library list is the only one checked to see if the member exists. For example, if you have two QCLSRC files on the library list, and the member you are checking for is in the second file on the library list, you will get the CPF9815 escape message. If you use a qualified object name, it does not matter if the object is on the library list. Only the specific object is checked for the member.

• CPF9820—You are not authorized to the library. This message occurs if you specify a qualified library name that exists but you are not authorized to the library. Note that CPF9820 will occur even if you have not specified the AUT parameter.

There are some other CPF98xx conditions on CHKOBJ that I never monitor for. I suspect there are also some unusual MCHxxxx conditions that may be bubbled up, but I wouldn’t monitor for them either.

If you specify an invalid command (such as describing a nonexistent object type), you will get the general CPF0001 escape message (you did not get by the command definition checking). A diagnostic message is sent prior to the CPF0001 escape to describe the specific error.

What I Like About CHKOBJ

The message you monitor for after CHKOBJ is nonambiguous. Many of the system commands have messages that describe multiple error conditions. These are reasonable when you are reading the message text, but when you are writing a program to handle specific error conditions, you want nonambiguous escape messages.

When I’m coding, I find it simpler to check first for expected error conditions with CHKOBJ rather than try to monitor and understand the error conditions on some failed command. In addition, I’ve memorized the important escape messages on CHKOBJ so that I don’t have to look for what to monitor for.

What I Don’t Like About CHKOBJ

The CPF9801 message says something like this:

Object xxx in library yyy not found.

You do not see the requested object type in the first-level text of the message. The object type specified is in the second-level text of the message, but I’d prefer to see it in the first level.

A solution is the CHKOBJ3 command in the TAA Productivity Tools. It uses unique text for most object types. For example, if a *FILE object type is missing, the text reads “File xxx in yyy not found.”

Another solution is to change the text of message description CPF9801, inserting “type *&5” right before “not found.” This way, CPF9801 reports something like “Object xxx in library yyy type *zzz not found,” which is much better. If you would like to make

this change on your system, run the Work with Message Descriptions (WRKMSGD) command, specifying a beginning of CPF9801. Then enter option 2 next to it, press Enter, and insert “type *&5” in the place I have indicated. Press Enter again, and CPF9801 is changed forever—or at least until you upgrade the operating system to a new version or release.

Another thing I don’t like about CHKOBJ is that normally you have to use a GOTO command to get around the case in which it is an error if the object does exist. For example:

CHKOBJ OBJ(FILEA) OBJTYPE(*FILE)
MONMSG MSGID(CPF9801) EXEC(DO) /* Not found */
GOTO GOODOBJ
/* Your bad object handling */
ENDDO /* Not found */
GOODOBJ: /* Your good object handling */

The problem with additional GOTO commands is that you can make a bad logic error by placing some commands between the ENDDO and the GOODOBJ label. The simple DO defined on the Monitor Message (MONMSG) command is a lot safer to use.

To handle the “reverse logic” situation, I use the CHKOBJ2 command in the TAA Productivity Tools.

CHKOBJ2 OBJ(FILEA) OBJTYPE(*FILE)
MONMSG MSGID(TAA9891) EXEC(DO) /* Found */
/* Your bad object handling */
ENDDO /* Found */

The CHKOBJ2 command just reverses the polarity of the command and sends you an escape message (TAA9891) if the object does exist.

An alternative solution is to use an &EXISTS variable, such as follows:

DCL &exists *LGL 1
CHGVAR &exists ‘1’
CHKOBJ &lib/&obj &objtype
MONMSG cpf9801 EXEC(CHGVAR &exists ‘0’)

Another thing that users typically want to know about objects is whether they are in use. CHKOBJ doesn’t check for this. You need the Allocate Object (ALCOBJ) command, which isn’t as clean-cut as CHKOBJ. ALCOBJ has a lot of restrictions within the command itself (for instance, you cannot allocate a printer or display file). The system also prevents meaningful function that could be achieved with a command like ALCOBJ, because it does not lock a program when it is called.

Some tools in QUSRTOOL and the TAA Productivity Tools can help, but they are not perfect because of the system limitations. You could look at the tools Check Active Program (CHKACTPGM), Check Active Object (CHKACTOBJ), and Check Active User (CHKACTUSR).

And the last thing about CHKOBJ I don’t like is that it supports only a specific qualified library name, *LIBL, or *CURLIB. Thus, you can’t ask whether PGMA exists anywhere in the system (but you can with DSPOBJD).

RTVOBJD Command

The RTVOBJD command provides all kind of information about the object. You can retrieve the create date, change date, last use date, size, owner, attribute, source member used to create the object (if any), etc.

When you prompt for the command, the numbers in the parentheses of the return values describe how to declare the variable to be used to hold the result. Figure 1 shows a portion of the RTVOBJD command prompt.

To return the owner name, you need to declare a variable of type *CHAR, with a length of 10. To return the auxiliary storage pool (ASP) of an object, you need to declare a variable of type *DEC, which has a length of (2 0).

To return both the owner and ASP, you would use code like this:

DCL &OWNER *CHAR LEN(10)
DCL &ASP *DEC LEN(2 0)
RTVOBJD OBJ(FILEA) OBJTYPE(*FILE) OWNER(&OWNER) ASP(&ASP)

If you return a date value, the dates come back as 13-byte character variables in the form of CYYMMDDHHMMSS. You have to substring out the date if you want just that piece of it. Note that the outfile used by the Display Object Description (DSPOBJD) command, QADSPOBJ, uses an MMDDYY format for some of the same dates (regardless of your job or system date format) and a separate field for time. The RTVOBJD SIZE parameter allows for a 15-digit number. This also differs from the DSPOBJD outfile file, which uses a 10-digit number (ODOBSZ) for size and then has an additional field (ODPUN) for bytes per unit to allow for larger sizes.

I use RTVOBJD frequently to determine which library an object exists in. For example, if the user specifies a library qualifier of *LIBL or *CURLIB, you can access the library by using the RTNLIB parameter on RTVOBJD. I have a lot of code that looks like this:

IF (%SST(&LIB 1 1) *EQ ‘*’) DO /* Get lib */
RTVOBJD OBJ(&LIB/&FILE) OBJTYPE(*FILE) RTNLIB(&LIB)
ENDDO /* Get lib */

The RTVOBJD command is used if the first position of the library name is an asterisk (*), indicating a special value. After these instructions, my code just uses the &LIB variable as the specific library name (either because the user entered it or because RTVOBJD found it).

One of the parameters that appears on RTVOBJD is USRDFNATR. This field (10 bytes) is left to your own imagination as to what you want to do with it. I am unaware of any CRT commands that allow you to set the attribute when you create an object. However, you can change the value with the QLICOBJD API. I front-ended the API with the CHGOBJD2 command in QUSRTOOL or the TAA Productivity Tools. To set the attribute, you just use this code:

CHGOBJD2 OBJ(xxx) OBJTYPE(*xxx) USRDFNATR(...)
To retrieve the attribute, you use this code:
DCL &USRDFNATR *CHAR LEN(10)
RTVOBJD OBJ(xxx) OBJTYPE(*xxx) USRDFNATR(&USRDFNATR)

Although CHKOBJ allows you to determine whether an object exists even if you are not authorized to it, you cannot use RTVOBJD unless you have some authorization. If you have any authorization, you can access the description, but a more typical set of code would look like this:

CHKOBJ OBJ(xxx) OBJTYPE(*xxx) AUT(*USE)
MONMSG MSGID(CPF9802) EXEC(DO) /* Not auth */
/* Your code for not authorized */
ENDDO /* Not auth */
RTVOBJD OBJ(xxx) OBJTYPE(*xxx) ...

RTVOBJD uses the same basic CPF98xx messages sent by CHKOBJ as well as some unique message IDs. So the alternative solution is to monitor for the CPF9802 message that will be sent by RTVOBJD:

RTVOBJD OBJ(xxx) OBJTYPE(*xxx) ...
MONMSG MSGID(CPF9802) EXEC(DO) /* Not auth */
/* Your code for not authorized */
ENDDO /* Not auth */

You can use the Display Library (DSPLIB) command to determine which objects you are not authorized to. The object name and type are listed, but the text description says *NOT AUTHORIZED. Neither DSPOBJD nor Work with Objects (WRKOBJ) lists objects you are not authorized to. QADSPOBJ, the outfile for DSPOBJD, will not show you the object, either.

Because RTVOBJD returns parameters, you can execute the command only in a CL program. If you are writing an HLL program like RPG and want object information, you can use the QUSROBJD API. Or you can use the RTVOBJD2 in the TAA

Productivity Tools. Your program would call the supplied program and receive back an externally described data structure with most of the typical object information.

Specific RTVxxx Commands

You can get a lot of general-purpose information about an object using RTVOBJD. However, the system offers other object information that is specific to the object type, such as a program or database file.

To get to this level of information, you can use either an API or one of the many RTVxxx commands in QUSRTOOL or the TAA Productivity Tools. For example, there are commands such as Retrieve Program Attribute (RTVPGMA), Retrieve Database File Attribute (RTVDBFA), Retrieve Job Description (RTVJOBD), and Retrieve Command Attribute (RTVCMDA).

Information Is the Object

When you are trying to control an application, CHKOBJ and RTVOBJD provide a simple means of checking and retrieving object information. If you are familiar with these commands, you can make a lot of good things happen.

Retrieve Object Description (RTVOBJD)

Type choices, press Enter.

Object . . . . . . . . . . . . . __________ Name

Library . . . . . . . . . . . *LIBL_____ Name, *LIBL, *CURLIB

Object type . . . . . . . . . . __________ *ALRTBL, *AUTL, *BNDDIR...

CL var for RTNLIB (10) . . __________ _ Character value

CL var for OBJATR (10) . . __________ _ Character value

CL var for USRDFNATR (10) . . __________ _ Character value

CL var for TEXT (50) . . ___________ Character value

CL var for OWNER (10) . . ___________ Character value

CL var for PGP (10) . . ___________ Character value

CL var for ASP (2 0) . . ___________ Number

CL var for OVFASP (1) . . ___________ Character value

CL var for CRTDATE (13) . . ___________ Character value

CL var for CHGDATE (13) . . ___________ Character value

CL var for SAVDATE (13) . . ___________ Character value

CL var for SAVACTDATE (13) . . ___________ Character value

CL var for RSTDATE (13) . . ___________ Character value

More...

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display

F24=More keys

Figure 1: Part of the RTVOBJD 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: