06
Sun, Oct
2 New Articles

How to Create an Exit Program

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

In the January/February 1995 issue of PC Support Expert, I described the new V3R1 techniques for installing an exit program on the AS/400 to monitor PC requests (see

“Servers, Subsystems and the Registration Facility”). In that article, I explained the new registration facility, which lets you create separate exit programs for each server in OS/400. You use the exit programs to permit or deny PC applications access to AS/400 resources, such as the database, folders, and programs. Exit programs work in addition to normal OS/400 system security.

Since then, several people have asked me how to monitor and control PC application requests. For example, they want to allow their users access to the file download process, but not allow file upload. This particular requirement is a greater problem in the V3R1 Windows client than in the previous DOS clients, as the download and upload functions are provided in the same program. I’ve created an example exit program to block file upload requests (PC to the AS/400). I’ll go through the steps you’ll need to follow to install this, or a similar, exit program.

What an Exit Program Does

When you use a Client Access/400 function on a PC, you usually interact with something on the AS/400. For example, you might do file transfers, use ODBC or data queues, or submit commands through Client Access/400. If OS/400 password and object security is sufficient, you don’t need to create and work with exit programs.

However, you might want more control over the functions than security can provide. For example, you might want to limit file transfers to certain days of the week or work hours. In some cases, you can use exit programs to assist in debugging; for example, you can capture SQL statements generated by ODBC. For those types of requirements, you can create and associate an exit program with a specific function provided by OS/400.


When you use a function that has an exit program associated with it, the exit program is called by OS/400. Each exit program uses two parameters. The first is the return code, a simple 1-byte field that indicates whether or not you will allow the function to proceed. If you set the return code to a value of ‘0’ (zero), the function is not allowed. The function is allowed if you set the return code to ‘1’ (one).

The second parameter includes several fields that identify the request, the user, and other details. You can include any logic you need in your exit program. The logic can examine the fields from the second parameter to determine if the request should be allowed. The sample program shown in this article demonstrates how to test values in the second parameter and set the return code.

Start with the Servers

To get the exit program working, we’ll start with the servers. These servers are software server programs, and have nothing to do with LAN server, the FSIOP, or other network hardware. Instead, the server programs are parts of OS/400 that respond to specific requests from clients for access to AS/400 resources.

For the exit program described here, you need to get into the registration facility. Type the command WRKREGINF (Work with Registration Information). A display similar to Figure 1 will appear. This lists all of the “exit points” that IBM has provided for the OS/400 servers. You need to identify the server for the function that you need to control.

Table 1 shows a list of servers that you might use with Client Access/400 clients, and the names of the exit points associated with them. For this example, I want to prevent file uploads, which is a function of the file transfer server. This is associated with exit point QIBM_QTF_TRANSFER. This exit point is used to monitor both file uploads and file downloads. You can determine what process is requested when the exit program is called by using fields in the second parameter.

Add the Exit Program

The exit program that we’ll use to control the file upload process is shown in Figure 2. This is CL program QGPL/TFREXIT. You can either enter the source code as shown, or download the code from file area 2 of the Midrange Computing BBS (the number is shown on page 2 of this issue of Client Access/400 Expert). I’ll explain how the program works below.

To add this exit program to the exit point, type number 8 next to the exit point name (the last entry shown in Figure 1). When you press Enter, you first go to an intermediate display of currently associated exit programs. You probably will not have a current exit program, so use the option on that display to add the exit program. The next display you’ll see is the Add Exit Program display, shown in Figure 3. Check that the exit point is correct. Enter the program number, which will always be 1 for this type of exit program. Next, enter the qualified name of the exit program. Finally, enter some text to describe the function of the program at this exit point.

The program does not have to exist at this point, but you’ll get an error message if the exit program does not exist or cannot be found at run time.

Set the Network Attributes

After creating your exit program and adding it to the server, you need to set your AS/400 network attributes. Use the Change Network Attributes (CHGNETA) command.


Page forward until you come to the display shown in Figure 4. You need to set the “Client request access” parameter to *REGFAC to point to the registration facility.

You may have already created an exit program for previous releases of Client Access/400 or PC Support/400. If you did, and if you referenced that exit program on the PCSACC parameter, you’ll need to move your references to the existing exit program to the registration facility. Because the PCSACC exit program was called for any server function (e.g., the same program is called for shared folders, file transfer, and data queues), you’ll have to determine which exit points in the registration facility need the exit program. You don’t have to make any changes to the existing exit program, but you will have to associate it with all of the exit points that correspond to the functions you were monitoring.

Test the Exit Program

You now have everything in place to test the exit program. You’ve created the CL exit program, gone into the registration facility and associated it with the transfer exit point, and changed your AS/400 PCSACC network attribute.

To test this program, start the Client Access/400 file transfer program. You can test the exit program with the DOS-based RTOPC and RFROMPC programs, but you’ll see the effect of this exit program more clearly if you test with the Windows-based file transfer. In that program, start by downloading a file. For the test, you can download the CL source member for the exit program to a PC file. Because you’re performing a download, the exit program will not stop the request. The exit program is called, but when it determines that the request is not for a file upload, it immediately exits. (The return code was set to ‘1’ when the exit program was first called, so the download request proceeds.)

After performing the download, start an upload of the same file back to the AS/400. This time, when the exit program is called, it sees the upload request. The sample exit program in this article sends a formatted message to the system operator message queue, asking if the upload should proceed. A sample of the message is shown in Figure 5. Note that this message is not a requirement of the exit program; it’s just an example for your testing. In most cases, you will probably not want to intervene manually; if you don’t want to allow the request, just set the return code to ‘0’ and return. Or, you might want to log the request, then return.

For your test, you can run the upload twice. The first time, respond ‘Y’ (yes) to the message, which will allow the upload to occur. The second time, respond ‘N’ (no) to prevent the upload. When the exit program returns with a ‘0’ return code value, the error message shown in Figure 6 is displayed at the PC. This is the specific error message for the file transfer program. Other client applications, rejected by other exit programs, will have error messages specific to them (e.g., shared folders will have a different error message).

Locating Information About the Exit Program Parameters

To find out what the parameters are that are passed to an exit program, you need to refer to the OS/400 Server Concepts and Administration V3R1 manual. Appendix A of that manual lists each exit point (as shown on the Work with Registration Information display), and describes the fields passed to your exit program in the second parameter.

The manual also contains model exit programs in RPG and CL for several types of exit points. You can create your own exit programs using any AS/400 language.


References

OS/400 Server Concepts and Administration V3R1 (SC41-3740, CD-ROM QBKAUX00).

Function Exit Point

File server (shared folders, IFS) QIBM_QPWFS_FILE_SERV Virtual print QIBM_QVP_PRINTERS File transfer QIBM_QTF_TRANSFER Message function QIBM_QMF_MESSAGE Data queues QIBM_QHQ_DTAQ Remote SQL QIBM_QRQ_SQL License management QIBM_QLZP_LICENSE Database server—initiation QIBM_QZDA_INIT Database server—native requests QIBM_QZDA_NDB1

(create file, add/clear/remove member, etc.) Database server—SQL requests QIBM_QZDA_SQL1

(see Appendix A) Database server—SQL catalog QIBM_QZDA_ROI1

(see Appendix A) Function Exit Point File server (shared folders, IFS) QIBM_QPWFS_FILE_SERV Virtual print QIBM_QVP_PRINTERS File transfer QIBM_QTF_TRANSFER Message function QIBM_QMF_MESSAGE Data queues QIBM_QHQ_DTAQ Remote SQL QIBM_QRQ_SQL License management QIBM_QLZP_LICENSE Database server—initiation QIBM_QZDA_INIT Database server—native requests QIBM_QZDA_NDB1

(create file, add/clear/remove member, etc.) Database server—SQL requests QIBM_QZDA_SQL1

(see Appendix A) Database server—SQL catalog QIBM_QZDA_ROI1

(see Appendix A)

Table 1: Exit Points Used with CA/400 Functions

/********************************************************************/

/* File transfer exit program - prompt to allow upload requests */
/********************************************************************/

tfrexit: pgm parm(&rtncode /* Return Code */ +

& parmcheck) /* Parms to check */
dcl var(&rtncode ) type(*char) len(1)
dcl var(&parmcheck) type(*char) len(4171)
dcl var(&msg ) type(*char) len(100)
dcl var(&msgreply ) type(*char) len(1)
dcl var(&usrprf ) type(*char) len(10)
dcl var(&appname ) type(*char) len(10)
dcl var(&rqstdfunc) type(*char) len(10)
dcl var(&objname ) type(*char) len(10)
dcl var(&libname ) type(*char) len(10)
dcl var(&mbrname ) type(*char) len(10)
dcl var(&fmtname ) type(*char) len(10)
dcl var(&rqstlenc ) type(*char) len(5 )
dcl var(&rqstlenn ) type(*dec ) len(5 0)
dcl var(&request ) type(*char) len(4096)
/********************************************************************/

/* Set return code to assume success */
/********************************************************************/

chgvar var(&rtncode) value(‘1’)
/********************************************************************/

/* Break out parameters from parm list field */

/* Get Requested Function first, return immediately if not upload */

/********************************************************************/

chgvar var(&rqstdfunc) value(% sst(&parmcheck 21 10))


if cond(&rqstdfunc * ne ‘REPLACE’) then(return)
/********************************************************************/

/* Upload request - get other parm values */
/********************************************************************/

chgvar var(&usrprf ) value(%sst(&parmcheck 1 10))
chgvar var(&appname ) value(%sst(&parmcheck 11 10))
chgvar var(&objname ) value(%sst(&parmcheck 31 10))
chgvar var(&libname ) value(%sst(&parmcheck 41 10))
chgvar var(&mbrname ) value(%sst(&parmcheck 51 10))
chgvar var(&fmtname ) value(%sst(&parmcheck 61 10))
chgvar var(&rqstlenc) value(%sst(&parmcheck 71 5))
chgvar var(&rqstlenn) value(&rqstlenc)
chgvar var(&request ) value(% sst(&parmcheck 76 &rqstlenn))
/********************************************************************/

/* Format prompt msg, send to QSYSOPR */
/********************************************************************/

chgvar var(&msg) value(‘User’ * bcat &usrprf)
chgvar var(&msg) value(& msg *bcat ‘requests upload + from PC to’)
chgvar var(&msg) value(& msg *bcat &libname * tcat ‘/’ )
chgvar var(&msg) value(& msg *tcat &objname * tcat ‘(‘ )
chgvar var(&msg) value(& msg *tcat &mbrname * tcat ‘,’ )
chgvar var(&msg) value(& msg *tcat &fmtname * tcat ‘).’)
chgvar var(&msg) value(& msg *bcat ‘Allow? (Y/N)’)
sndusrmsg msg(&msg) tomsgq(*sysopr) msgrpy(&msgreply) if cond(&msgreply * ne ‘Y’) then( +

chgvar var(&rtncode) value(‘0’))
endpgm •

Figure 2: CL Exit Program QGPL/TFREXIT

How_to_Create_an_Exit_Program05-00.jpg 450x309

Figure 3: The ADDEXITPGM Command


How_to_Create_an_Exit_Program06-00.jpg 450x309

Figure 4: CHGNETA Display for Attribute PCSACC

How_to_Create_an_Exit_Program06-01.jpg 450x309

Figure 5: Message Sent to QSYSOPR from Exit Program

How_to_Create_an_Exit_Program06-02.jpg 450x130

Figure 6: Error Sent to User When Request is Cancelled by Exit Program


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: