MC Press Online

How to Create an Exit Program

Contributed by Craig Pelkie Wednesday, 31 May 1995 Last Updated Wednesday, 31 May 1995

What an Exit Program Does

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. Ive created an example exit program to block file upload requests (PC to the AS/400). Ill go through the steps youll 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 dont 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
http://www.mcpressonline.com Powered by Joomla! Generated: 25 September, 2008, 23:19

MC Press Online

parameter and set the return code.

Start with the Servers

To get the exit program working, well 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 well 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). Ill 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 youll 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 youll 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.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 25 September, 2008, 23:19

MC Press Online

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, youll 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), youll have to determine which exit points in the registration facility need the exit program. You dont 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. Youve 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 youll see the effect of this exit program more clearly if you test with the Windowsbased 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 youre 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; its just an example for your testing. In most cases, you will probably not want to intervene manually; if you dont 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.
http://www.mcpressonline.com Powered by Joomla! Generated: 25 September, 2008, 23:19

MC Press Online

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 serverinitiation QIBM_QZDA_INIT Database servernative requests QIBM_QZDA_NDB1

(create file, add/clear/remove member, etc.) Database serverSQL requests QIBM_QZDA_SQL1

(see Appendix A) Database serverSQL 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 serverinitiation QIBM_QZDA_INIT Database servernative requests QIBM_QZDA_NDB1

(create file, add/clear/remove member, etc.) Database serverSQL requests QIBM_QZDA_SQL1

(see Appendix A) Database serverSQL 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 */ /********************************************************************/

http://www.mcpressonline.com Powered by Joomla! Generated: 25 September, 2008, 23:19

MC Press Online

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 */ /********************************************************************/

http://www.mcpressonline.com Powered by Joomla! Generated: 25 September, 2008, 23:19

MC Press Online

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

http://www.mcpressonline.com

Powered by Joomla!

Generated: 25 September, 2008, 23:19

MC Press Online

Figure 5: Message Sent to QSYSOPR from Exit Program

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

http://www.mcpressonline.com

Powered by Joomla!

Generated: 25 September, 2008, 23:19