Brief: Keeping track of the PTFs on a system is a necessary but time consuming task. Keeping multiple systems at the same PTF level is even more challenging. The Display PTF utility is a client/server application to help make that chore more manageable.
Throughout my career, it has often fallen on me to keep multiple AS/400s at the same PTF level. Reviewing the PTFs for even a single system is not as intuitive as I would like it to be. Licensed programs and their associated PTFs are hierarchical data. The display of the PTF data on the AS/400 screen isn't clearly organized that way. The utility I've written solves this problem.
Developing applications for a client/server Graphical User Interface (GUI) environment gives you the opportunity to greatly enhance an application's ease of use. Therefore, I used the Client Access (PC Support) APIs to access the data and Multiple Document Interface (MDI) to show the data from multiple systems. I used the MSOUTLIN Visual Basic Extension (VBX) to organize the data into the hierarchical format I wanted.
There's Got To Be a Better Way
The OS/400 Display Program Temporary Fix (DSPPTF) command allows you to review the PTFs on the system. The command can show you the PTFs for all licensed programs, but it walks you through the licensed programs in a specific order. I felt I could come up with a better way to review the PTFs.
I wasn't satisfied with any of the text screen solutions I came up with. The data could be represented in a hierarchical format, but with such a long list of PTFs, finding your way through the list to the correct licensed program was difficult. I wanted the user to be able to expand and contract the list of PTFs based on the licensed program.
To compare the PTFs on different systems, you're probably going to resort to printing out the PTF listings and comparing them. You could probably use two terminal emulation sessions under Windows, but the two displays get out of sync when a PTF is listed on one system but not the other. After the screens get out of sync, displaying them side by side serves little purpose. Client/server and GUI gave me a better way to do this.
And There Is
The first part of my solution involves getting to the data. I use the Client Access APIs-specifically the transfer function. Rather than showing the PTF data live, I store it in an outfile and update the outfile at the user's request. Because PTFs are not usually put on the system every day, the data isn't volatile. Updating the outfile can be a long process, but since it doesn't change every day, using an outfile is an acceptable compromise.
I've always thought that Open Database Connectivity (ODBC) was superior in many ways to the Client Access APIs. However, I didn't know that empirically. I've been developing client/server software for quite a while now, and I've always used ODBC. One of the reasons I felt ODBC was better was because of the potential to create code that is independent from the back-end database. I also felt that ODBC was better simply because it is easier to use than the APIs, but I wasn't as sure about that part.
Until now. After writing this utility I'm convinced that using the APIs is a vast sinkhole for programmer time. I could have developed the same utility using ODBC in one tenth the time it took me using the APIs. Many people complain about ODBC's performance, but I've learned that I can write software using ODBC with performance close to that of APIs. But that is a topic for a future article. In this case, I used the Client Access APIs for my utility because I don't have access to an ODBC driver. Certain functions, such as checking to see if the Client Access router is active, can only be written with the APIs, so this utility demonstrates how to use them. (For more information, see "PC Support Windows APIs" in this issue.)
The second part of the solution is how to present the data if a user has multiple AS/400s. MDI lets you do that. The "Multiple Document Interface and Visual Basic" sidebar explains the basics of MDI and how to use it in Visual Basic.
The last part of the solution is the MSOUTLIN VBX, which is a custom control included with the Visual Basic Professional Edition. To understand more about VBXs, look for an upcoming article in Midrange Computing. The MSOUTLIN VBX lets you display groups of indented data and allows you to expand and contract the list to show subordinate items. The control can also display a graphic such as a plus sign to indicate that a group can be expanded.
How to Use the Display PTF Utility
When you double-click on the DSPPTF application icon, different things will happen depending on whether or not Client Access is connected to more than one system. If it is connected to only one system, the utility shows you the PTFs for that system. If Client Access is connected to more than one system, you will see a window like the one shown in 1.
When you double-click on the DSPPTF application icon, different things will happen depending on whether or not Client Access is connected to more than one system. If it is connected to only one system, the utility shows you the PTFs for that system. If Client Access is connected to more than one system, you will see a window like the one shown in Figure 1.
This window shows you a list of all the systems Client Access is attached to. You can use the mouse to click on the system with the PTFs you want to see. After selecting one or more systems, you can click on the Show PTFs button.
At this point, the utility checks to see if a PTF outfile exists on all the systems that you've selected. If an outfile doesn't exist, the program displays a message box like the one shown in 2. Creating the outfile takes a few minutes, so the program gives you the option not to create the outfile right away. If you choose to defer outfile creation, you will not see the MDI child window for that system. Once the outfile exists, the utility retrieves the records and displays the list of PTFs.
At this point, the utility checks to see if a PTF outfile exists on all the systems that you've selected. If an outfile doesn't exist, the program displays a message box like the one shown in Figure 2. Creating the outfile takes a few minutes, so the program gives you the option not to create the outfile right away. If you choose to defer outfile creation, you will not see the MDI child window for that system. Once the outfile exists, the utility retrieves the records and displays the list of PTFs.
3 shows the display for two systems. When you click on a plus sign, the utility expands the list and shows you the PTFs for that licensed program. The plus sign then changes to a minus sign. If you click on a minus sign, the utility collapses the list for that licensed program.
Figure 3 shows the display for two systems. When you click on a plus sign, the utility expands the list and shows you the PTFs for that licensed program. The plus sign then changes to a minus sign. If you click on a minus sign, the utility collapses the list for that licensed program.
The Close button closes the MDI child window for that system. If only one window is open, the Close button closes the entire application. You can also double-click on the control-menu box in the upper left hand corner of the child window. To close the entire application without having to close all the child windows, double-click on the control-menu box in the upper left corner of the MDI parent window.
The Update List button recreates the PTF outfile on the AS/400. Because running the outfile update can take several minutes, the program displays a message box asking you to confirm that you want to run this function. When you click the Yes button on the message box, the program recreates the outfile and updates the display.
The Display PTF Utility
Now I will discuss the code. The next section explains the pertinent parts of the forms and modules in the utility. Not all of the code is included with this article. Only the sections that help you understand what I'm doing are printed. You can download the code in its entirety (including a Windows setup program) from the MC-BBS. 4 details the forms and objects used by this utility and their initial property settings.
Now I will discuss the code. The next section explains the pertinent parts of the forms and modules in the utility. Not all of the code is included with this article. Only the sections that help you understand what I'm doing are printed. You can download the code in its entirety (including a Windows setup program) from the MC-BBS. Figure 4 details the forms and objects used by this utility and their initial property settings.
PTFMDIForm-The Headwaters of the Utility
The PTFMDIForm is the startup form. VB transfers control to this form when you start the application. Specifically, VB will go to the MDIForm_Load event. This form does the testing to see if it is okay to continue with the program. In 5, you can see the declaration section of the form. It has the function declarations for the two Client Access APIs that are used by this form.
The PTFMDIForm is the startup form. VB transfers control to this form when you start the application. Specifically, VB will go to the MDIForm_Load event. This form does the testing to see if it is okay to continue with the program. In Figure 5, you can see the declaration section of the form. It has the function declarations for the two Client Access APIs that are used by this form.
First, the code in this form checks to see if the Client Access router is loaded. You can see the code that performs this check in section A of 6. The code uses the EHNAPPC_IsRouterLoaded API. If the router is not loaded, then nothing in the program will work, so the program ends.
First, the code in this form checks to see if the Client Access router is loaded. You can see the code that performs this check in section A of Figure 6. The code uses the EHNAPPC_IsRouterLoaded API. If the router is not loaded, then nothing in the program will work, so the program ends.
Next, the program puts a list of the Client Access-attached systems into a variable. This code segment uses the EHNAPPC_QuerySystems API (section B in 6). The API returns two values. The first is an integer value that contains the number of systems Client Access is attached to. The second is a string value that contains the names of those systems. If there are no Client Access connections to any system, the program ends.
Next, the program puts a list of the Client Access-attached systems into a variable. This code segment uses the EHNAPPC_QuerySystems API (section B in Figure 6). The API returns two values. The first is an integer value that contains the number of systems Client Access is attached to. The second is a string value that contains the names of those systems. If there are no Client Access connections to any system, the program ends.
When you are connected to only one system, the utility works a little differently than when you are connected to more than one system (section C in 6). When you are attached to one system, the program executes the code starting at section D in 6. First, the program checks to see if the PTF outfile exists by running the PTFOutfileExist function (section E in 6). This code uses the EHNSR_SubmitCommand API. The program runs the Check Object (CHKOBJ) command to see if the file MCPTFLIST in the library QGPL exists. If the file is not found, an error message (CPF9801) is returned, which tells the utility that the outfile doesn't exist. The program then displays a message box asking if the user wants to create the outfile.
When you are connected to only one system, the utility works a little differently than when you are connected to more than one system (section C in Figure 6). When you are attached to one system, the program executes the code starting at section D in Figure 6. First, the program checks to see if the PTF outfile exists by running the PTFOutfileExist function (section E in Figure 6). This code uses the EHNSR_SubmitCommand API. The program runs the Check Object (CHKOBJ) command to see if the file MCPTFLIST in the library QGPL exists. If the file is not found, an error message (CPF9801) is returned, which tells the utility that the outfile doesn't exist. The program then displays a message box asking if the user wants to create the outfile.
If the user clicks the Yes button to create the outfile, the program runs the CreateOutfile function (section F in 6). This code uses the EHNSR_SubmitCommand API. The command run by the program is the Display Program Temporary Fix (DSPPTF) command to the outfile MCPTFLIST in QGPL. Then the program uses the EHNSR_StopConversation API to end the conversation started by the SubmitCommand API (section G in 6).
If the user clicks the Yes button to create the outfile, the program runs the CreateOutfile function (section F in Figure 6). This code uses the EHNSR_SubmitCommand API. The command run by the program is the Display Program Temporary Fix (DSPPTF) command to the outfile MCPTFLIST in QGPL. Then the program uses the EHNSR_StopConversation API to end the conversation started by the SubmitCommand API (section G in Figure 6).
If you click the No button to indicate that you don't want the outfile created at this time, the program ends. Because Client Access is attached to only one system, and no outfile exists, there is no point in continuing the program.
At this point in the code, you will see a statement setting the Tag property of a PTFChildren array to 1. PTFChildren is called a form array.
I created a form called PTF_List. For each attached system, the program uses a new instance of that form using the form array PTFChildren. Setting the property of a form instance that isn't loaded implicitly loads and shows the form. The program sets the Tag property to 1 which shows that form instance (section H in 6).
I created a form called PTF_List. For each attached system, the program uses a new instance of that form using the form array PTFChildren. Setting the property of a form instance that isn't loaded implicitly loads and shows the form. The program sets the Tag property to 1 which shows that form instance (section H in Figure 6).
Back at code section C in 6, the program branches based on whether Client Access is attached to more than one system. If it is, the program shows a form called SysList modal. Showing a form modal requires that users close the form before they continue to use other forms in the application. According to that definition, I didn't need to use a modal form, but I used it anyway because it made the window behave the way I wanted it to. The result is that the SysList form is shown by itself. If I had shown this form modeless, it would have displayed with the PTFMDIForm.
Back at code section C in Figure 6, the program branches based on whether Client Access is attached to more than one system. If it is, the program shows a form called SysList modal. Showing a form modal requires that users close the form before they continue to use other forms in the application. According to that definition, I didn't need to use a modal form, but I used it anyway because it made the window behave the way I wanted it to. The result is that the SysList form is shown by itself. If I had shown this form modeless, it would have displayed with the PTFMDIForm.
The last code run under the PTF-MDIForm before it is shown uses the arrange method to tile the MDI child windows vertically. This method sizes all of the MDI child windows so that their combined size fills the MDI parent's client area.
SysList Form-Coffee, Tea, or S1034786
The SysList form shows a list of the Client Access-attached systems. In the Form_Load event, the code loads the list box with the names of all the systems (section I in 7). At the start of the program, the program loads the names of all Client Access-attached systems into the global string gsSysNames. The code loops through that string, and the name of the next system is at each 10-byte offset.
The SysList form shows a list of the Client Access-attached systems. In the Form_Load event, the code loads the list box with the names of all the systems (section I in Figure 7). At the start of the program, the program loads the names of all Client Access-attached systems into the global string gsSysNames. The code loops through that string, and the name of the next system is at each 10-byte offset.
Section J in 8 shows the code that runs every time a user clicks on an element in the list box. This section tests to see if there are any selected items in the list box. Clicking on an item in the list box toggles the item between selected and not selected. If any selected items are in the list box, the program enables the cmdShowPTFs button. Having the button disabled until an item is selected from the list box keeps the code in the button's Click event from executing until at least one system is selected.
Section J in Figure 8 shows the code that runs every time a user clicks on an element in the list box. This section tests to see if there are any selected items in the list box. Clicking on an item in the list box toggles the item between selected and not selected. If any selected items are in the list box, the program enables the cmdShowPTFs button. Having the button disabled until an item is selected from the list box keeps the code in the button's Click event from executing until at least one system is selected.
When the user clicks on the Show PTFs button, the program loops through all the items in the list box. The program counts how many systems are selected, and the form array PTFChildren is redimensioned to the correct number of form instances (section K in 9).
When the user clicks on the Show PTFs button, the program loops through all the items in the list box. The program counts how many systems are selected, and the form array PTFChildren is redimensioned to the correct number of form instances (section K in Figure 9).
The program then loops through the list of systems in the list box. For each selected system, the program checks to see if the outfile exists using the PTFOutfileExist function (section L in 9). If the outfile doesn't exist, the program shows a message box asking the user if he wants it created now. If the user clicks the Yes button, the program creates the outfile (section M in 9).
The program then loops through the list of systems in the list box. For each selected system, the program checks to see if the outfile exists using the PTFOutfileExist function (section L in Figure 9). If the outfile doesn't exist, the program shows a message box asking the user if he wants it created now. If the user clicks the Yes button, the program creates the outfile (section M in Figure 9).
If the user clicks the No button, or if there is some other problem, the program sets the FormDeleted array element equal to True. The program uses this array to keep track of deleted form instances. Setting the FormDeleted element to True later causes the program not to display the form. This approach is a fairly common way to keep track of form instances. It allows you to conserve memory by writing code to reuse "deleted" form instances instead of creating new ones.
At code section N in 9, the program implicitly loads and shows the form instance by setting the Tag property. The value of the Tag property is the index of the element (or instance) of the form array. The program loops through this code until all appropriate MDI child windows are created.
At code section N in Figure 9, the program implicitly loads and shows the form instance by setting the Tag property. The value of the Tag property is the index of the element (or instance) of the form array. The program loops through this code until all appropriate MDI child windows are created.
PTF_List MDI Child Window-A PTF List Even I Can Understand
Once the program implicitly loads the form instance, it transfers execution to the Form_Load event of the PTF_List window instance. The first thing it does is try to open the PTF outfile (section O in 10).
Once the program implicitly loads the form instance, it transfers execution to the Form_Load event of the PTF_List window instance. The first thing it does is try to open the PTF outfile (section O in Figure 10).
The OpenPTFFile function uses the EHNTF_STF API (section P in 11). This API works a little differently than most others. The API has many functions built into it. Instead of calling different APIs for each function, you pass this API an integer value that tells the API what you want it to do. For the specific details of all the APIs used in this utility, see the PC Support/400 API Reference.
The OpenPTFFile function uses the EHNTF_STF API (section P in Figure 11). This API works a little differently than most others. The API has many functions built into it. Instead of calling different APIs for each function, you pass this API an integer value that tells the API what you want it to do. For the specific details of all the APIs used in this utility, see the PC Support/400 API Reference.
In this case, the program passes the API a transfer request 1, which says that the program wants to open a transfer request. The API then runs an SQL statement, but doesn't return any records, just a return code. Later the program will use the API with a different transfer request that says it wants to get a record returned by the SQL statement.
If there is a problem opening the PTF file, the return code will not be zero. If the return code is non-zero, the PTF file is closed and the MDI child window for this system will not be displayed.
The LoadOutline subroutine loops until it gets a non-zero return code. The program calls the GetPTFRecord function. The program uses the EHNTF_STF API with a transfer function code of 3. The API returns a single record into a buffer. This buffer is outside the memory accessible from Visual Basic, so you need to use another API to get to the data.
To copy the data to a Visual Basic variable, the program uses the EHNDT_MemCopy API (section Q in 12). This API is contained within the PCSMCPY.DLL Dynamic Link Library (DLL) which IBM supplies as part of QIWSTOOL. If you download the code for the PTF utility from MC-BBS, the PCSMCPY.DLL file is included and will be installed by the setup program. The MemCopy API copies the record to a string; then the program uses string functions to get the actual field values based on the known lengths of the fields.
To copy the data to a Visual Basic variable, the program uses the EHNDT_MemCopy API (section Q in Figure 12). This API is contained within the PCSMCPY.DLL Dynamic Link Library (DLL) which IBM supplies as part of QIWSTOOL. If you download the code for the PTF utility from MC-BBS, the PCSMCPY.DLL file is included and will be installed by the setup program. The MemCopy API copies the record to a string; then the program uses string functions to get the actual field values based on the known lengths of the fields.
If the program didn't get an error getting the PTF record, it converts the code for the status of the PTF to a text description (section R in 13). The outfile has a text description of the status, but I couldn't find a way to shorten the description to the length I needed and still have it be meaningful. So I decided to have the program convert the code to a text description.
If the program didn't get an error getting the PTF record, it converts the code for the status of the PTF to a text description (section R in Figure 13). The outfile has a text description of the status, but I couldn't find a way to shorten the description to the length I needed and still have it be meaningful. So I decided to have the program convert the code to a text description.
After the PTF status code is converted to text, the program is ready to add the data to the outline in the LoadOutine subroutine using the AddItem method. For the outline control, you also need to specify the indent level.
The program uses the variable sSaveLicPgm to handle a level break situation for licensed programs. When the program reads a PTF record for a new licensed program, it adds an item to the outline at indent level 1 for the licensed program. Then the program adds the PTF item to the outline at indent level 2 (section S in 14). Return code 8191 indicates the end of file, and the program exits the LoadOutline subroutine.
The program uses the variable sSaveLicPgm to handle a level break situation for licensed programs. When the program reads a PTF record for a new licensed program, it adds an item to the outline at indent level 1 for the licensed program. Then the program adds the PTF item to the outline at indent level 2 (section S in Figure 14). Return code 8191 indicates the end of file, and the program exits the LoadOutline subroutine.
The program then uses the ClosePTFFile function. The code again uses the EHNTF_STF API. It uses transfer function 5 (section T in 15). At this point, you are ready to show the outline.
The program then uses the ClosePTFFile function. The code again uses the EHNTF_STF API. It uses transfer function 5 (section T in Figure 15). At this point, you are ready to show the outline.
A button on the MDI child window is labeled "Update List." This button gives the user a way to update the outfile on the system. It can take a while to run the update of the outfile, so instead of making the data live (updating the outfile every time the program runs), I used this button. The code for the button is in the cmdUpdate_Click event.
Because this can be a long-running function, the program displays a message box to confirm that the user really wants to do this. If the user presses the Yes button, the program clears the outline using the Clear method (section U in 16-page 46). Then the program runs the CreateOutfile function. After that, the program runs the OpenPTFFile, LoadOutline, and ClosePTFFile functions just like in the Form_Load event.
Because this can be a long-running function, the program displays a message box to confirm that the user really wants to do this. If the user presses the Yes button, the program clears the outline using the Clear method (section U in Figure 16-page 46). Then the program runs the CreateOutfile function. After that, the program runs the OpenPTFFile, LoadOutline, and ClosePTFFile functions just like in the Form_Load event.
Future Enhancements
This utility could be improved in many ways. You could display the descriptions for the licensed programs instead of their code. You could add a menu item to let you display the PTFs for additional systems after the initial selection. What you choose to do at this point is up to you. My hope is that you can see how some of the decisions are made in client/server design, and that you will walk through the code to see how they are implemented. In doing so, you will see some of the issues involved in designing applications using an event-driven language and issues involving database access. From there, you can create your own client/server success stories.
Jim Hoopes is a senior technical editor for Midrange Computing.
REFERENCE PC Support/400 API Reference (SC41-8254, CD-ROM QBKA6102).
The Display PTF Client/Server Utility
Figure 1 The Select Systems Window
UNABLE TO REPRODUCE GRAPHIC
The Display PTF Client/Server Utility
Figure 2 The PTF Outfile Creation Confirmation Message Box
UNABLE TO REPRODUCE GRAPHIC
The Display PTF Client/Server Utility
Figure 3 The PTF Display
UNABLE TO REPRODUCE GRAPHIC
The Display PTF Client/Server Utility
Figure 4 Forms Controls and Their Properties
UNABLE TO REPRODUCE GRAPHIC
The Display PTF Client/Server Utility
Figure 5 Figures 5 - 16
All components for this utility are contained in the self-extracting file: DSPPTPKG.EXE This file can be found in the download area of the MC-BBS.
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online