How to Create an Exit Program

Programming - General

Written by Craig Pelkie

Wednesday, 31 May 1995 18:00

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

Figure 3: The ADDEXITPGM Command

Figure 4: CHGNETA Display for Attribute PCSACC

Figure 5: Message Sent to QSYSOPR from Exit Program

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

CeAbout the Athor:

< Prev Next >

Last Updated on Wednesday, 31 May 1995 18:00

You must be logged in to view or make comments on this article

Top of Form

User Rating: / 0

Poor Best Rate vote

com_content 4482 http://www .mcpr

Bottom of Form

MC-STORE.COM

Home | Publications | News | Events | Buyer's Guide | Forums | Videos | Popular | Archive | Bookstore

© Copyright 2013 MC Press Online, LLC | Privacy Policy | Search | RSS | FAQ | Contact Us | Write For Us | Editorial Review Board | Advertise | Site Map