Wed, Apr
5 New Articles

System Object Access--Application or API?

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

One of the more unusual components of the V3R1 Client Access for Windows 3.1 client is the recently available System Object Access, or SOA. Available now as a suite of PTFs, and scheduled to be shipped with the refresh shipment of CA/400, SOA provides GUI-based system control functions. The initial applications include printer output, job control, print control, job log, and messages.

Even though these functions are robust replacements for OS/400 command line operations, they might not, in and of themselves, generate much excitement. Documentation available last year indicated that the functions would be expected to perform slower than the equivalent command line function. However, the Windows programs provided with SOA seem to be only half of the story. The other half is that IBM is also providing the application program interfaces (APIs) used to create the SOA applications, along with the source code used in the applications. This means that, in addition to the programs that IBM provides, other vendors or you may create tailored versions of SOA. Also, I doubt that IBM’s intention is to provide APIs only for printer and job control. I believe this first set of APIs is intended as a demonstration of what is to come, and points the way to the GUI-enabled OS/400 of the future.

What’s Available Now

You don’t have to wait for new releases of OS/400 or hardware to see where this is leading. You can either obtain the PTF suite or install SOA during the refresh cycle. I’ll take you through the steps needed to load from the PTFs.

The PTF to order is SF21273 for licensed program 5763-XC1. This is the Client Access/400 for Windows 3.1 SBCS version. The PTF is available in English only. When you send the PTF order, specify DELIVERY(*ANY) and ORDER(*REQUIRED) on the SNDPTFORD (Send PTF Order) command. The PTF includes nine corequisite

PTFs, which are over 6MB in size. The PTFs are sent to you on a tape, which you can then install with the INSPTF (Install PTF) command.

When installed with PTFs, the SOA code is put into the QPWXCWN directory (the CA/400 Windows directory in the root file system). In order to install the SOA code on your PC, you need to update the CA/400 for Windows setup program. To do that, you need to run the CA/400 update function to copy the revised setup program code from QPWXCWN to your PC.

After running the update function, you start the setup program from the CA/400 program group. The setup program group now includes an icon for System Object Access/AFP Viewer. Clicking the icon causes the SOA and the Advanced Function Printer viewer code to be copied to your PC. This is a long-running process, during which time a progress box is displayed.

After the setup program is done, you have two new icons in your CA/400 for Windows program group. Those icons are for System Object Access and the AFP Viewer. Several other files are copied to your PC, as indicated in Table 1. These files include documentation and sample programs using SOA APIs.

Currently available documentation indicates that the setup process for SOA will be simplified in the refresh. Even so, ordering and installing the PTFs and configuring SOA on my PC were not difficult or especially time-consuming tasks.

SOA Functions

The SOA functions that are provided include programs to work with printer output, control jobs, work with printers, display the job log of the SOA job, and work with messages. You access these functions by clicking on the SOA icon in your CA/400 for Windows program group. That takes you to the program group shown in Figure 1.

If you can connect to more than one AS/400, you can choose the system using the System:Select AS/400 System option. That displays the simple dialog shown in Figure 2. This dialog is tied to the AS/400 Connection dialog, the standard Windows sign- on that you use to start CA/400 functions, if you press the AS/400 connection button.

Once you have a connection to an AS/400, you can start using SOA functions. You can run functions for more than one AS/400 simultaneously by making the connection, starting the function, then making the connection to the other AS/400 and starting the function for that system.

Printer Output Function

Perhaps the premier function that shows off most of the capabilities of SOA is the printer output program. Clicking the printout output icon in the SOA program group presents a list display, shown in Figure 3. Using the mouse, I click on the Printer column of the second entry. Doing so places a right-arrow button in the Printer column, next to the Not Assigned text. This is shown in Figure 4. Clicking that right arrow brings up the Printer dialog, where I can specify the name of the printer to assign to the spool file. Within the Printer dialog, I click the Find... button, which brings up the Find Printer dialog. That dialog lists all of the printers on the AS/400. I then select a printer from that list, which is subsequently assigned to the spool file.

Another example of SOA operations is the pop-up menu. Figure 5 shows the menu, which I invoke by clicking the right mouse button. The pop-up menu operations apply to the highlighted spool file, or group of spool files, if I select multiple spool files. (Multiple selection is designated by pressing either the Shift or the Ctrl key while indicating your selections with the mouse. Shift is used to select a from/through group of list entries,

Ctrl is used to select individual entries for the set.) The pop-up menu shows actions that apply to the type of object being operated on; in this case, the actions apply to spool file entries.

Selecting the Properties menu item in the pop-up menu displays printer output properties, shown in Figure 6. This display replaces the CHGSPLFA (Change Spool File Attributes) function available on the AS/400 WRKOUTQ (Work with Output Queues) command display. The Property/Value list shown in Figure 6 is one of the few rough spots that I encountered in the SOA suite. I think that it would be preferable to use a tab control here (similar to the option settings available in programs like Word for Windows 6.0 or Excel 5.0), or the OS/2 notebook control. I hope that IBM will reconsider their implementation of this particular aspect of SOA, as it is cumbersome to have to scroll through the property list. It looks like the green screen bug was here.

Regardless, this brief look at the operations supported on the printer output list is characteristic of the other SOA functions. Each function starts with a list display, from which you can select one or more list entries. You can perform actions on entries using the pop-up menu, menu items, or tool bar icons.

So What Else is New?

Simply having replacement list displays for OS/400 commands is not really that exciting. True, you can use the mouse to control things but, to some extent, you can do that with the RUMBA or PC5250 emulation programs.

Where you start to see a difference, and can perhaps see where IBM is leading, is in the configuration options for the displays. Because we are no longer in the fixed-format world of the dumb terminal, we can easily select the information to include on the list display. An example of this is shown in Figure 7. Using the Columns dialog, you select the columns and data that you want to include in the printer output list display. You also specify the order in which you want the columns to appear. You can save your customized view of the list for easy recall.

Another option, which is enabled through both the use of the GUI interface and the use of the system list APIs to generate the list data, is the Sort dialog. This is shown in Figure 8. Using this dialog, you can specify the sort order of the list, based on columns of data available.

A final option available for the list displays is the filter dialog, shown in Figure 9. Using this dialog, you can select the list entries to be included, based on a number of selection criteria.

You can alter each of these customizations as needed. The list display is refreshed after changing any of the selections. Compare this to the equivalent OS/400 commands, where you have to exit the list display to run the command again (for example, the Work with Spooled Files command).

Viewing Spooled Files

SOA includes the capability of viewing spooled files through the printer output list display. Spool files are viewed through a subset of the Advanced Function Printer Viewer (AFP Viewer) program that is included with SOA. Using the viewer does not require that you have an active terminal emulation session; the spool file is presented within the viewer window itself.

You view a spool file on the list by double-clicking the list entry, or by clicking the Open printer output toolbar icon for a highlighted entry. The first time you select an entry for viewing, you will probably get the error message shown in Figure 10.

This struck me as a remarkable message in that it was not only complete, concise, and comprehensible, but also correct. Going into a terminal emulation session and entering the command let me then continue with the view operation. You can prevent the message from reoccurring by using the ADDPJE (Add Prestart Job Entry) command, using the parameters shown in Figure 10.

Figure 11 shows a sample of the AFP Viewer output for a spool file. There are many image manipulation commands included on the viewer, including a print function to print the spool file to your Windows printer.

The AFP Viewer Trial

The version of the AFP Viewer program provided with SOA is considered a trial version. The first 25 times you use the viewer, you can use most of the functions available in the full AFP Viewer program. In addition to spool file viewing, there are functions for creating overlays, page segments, viewing AFPDS/SCS/ ASCII spool files, viewing graphics files (TIFF, PCS, DIB, GIF), and other functions. You can upgrade to the full- function AFP Viewer program by following the instructions shown in Figure 12. These instructions are displayed from the Upgrade menu option on the viewer, and are also included in the CASOA.DOC file included with SOA.

Other SOA Functions

Other list functions included with SOA include the job list, printer list, message list, and job log. All of these lists include similar functionality to the printed output list, and provide similar customization options. All of the functions provide access to all of the properties and attributes of the list entries displayed (for example, I have shown only a few of the functions associated with the printed output list display). Of the SOA functions, the Job Log is probably the least useful, as it displays only the job log of the job associated with the SOA functions.

A Step in the Right Direction

As I mentioned elsewhere in this issue, I think that SOA might be the sleeper application of CA/400. IBM is moving in the direction of providing a GUI front end to the AS/400. They started with what is probably the most frequently used operational functions: working with spool files and printers. For the most part, they have provided a very well- implemented interface.

My understanding is that SOA will be available for new Windows clients and for the OS/2 client. I hope that IBM will consider incorporating more GUI interface techniques; for example, the previously mentioned tab/notebook control for property groups, and drag-and-drop functionality where appropriate.

I have not yet been able to compare SOA with Graphical Operations, which shipped as part of the V3R1 initial release. My understanding is that SOA replaces GraphicOps. If you are just getting started with V3R1 CA/400, you may want to skip GraphicOps and go right to SOA.


Header files (.H) files for SOA APIs Library files (.LIB) files for SOA APIs Sample C programs for SOA APIs

LSTJOB - list jobs LSTMSG - list messages LSTPRT - list printers

LSTSPLF - list spool files Source for sample C programs Abstract for C programs (WSOASAMP.ABS)

Sample Visual Basic program using SOA APIs

SOASAMP Source for sample Visual Basic program Abstract for Visual Basic program (SOASAMP.ABS)

Source for sample SmallTalk program using SOA APIs Source for class SOACalls, used in SmallTalk program

In directory CAWIN:

General overview of SOA and AFP Viewer (CASOA.DOC) SOA API Guide and Reference (CASOAAPI.DOC)

In directory CAWINDATA:

Information about AFP Workbench for Windows (READ.ME) Information about AFP Print Driver for Windows (README.DOC)

Table 1: Files Included with SOA Figure 1: System Object Access Program Group Figure 2: Choosing an AS/400 System to Work With

System_Object_Access_Application_or_API-05-00.jpg 450x238

System_Object_Access_Application_or_API-05-01.jpg 450x263

System_Object_Access_Application_or_API-06-00.jpg 450x337

Figure 3: Printer Output List Figure 4: Selecting a Printer for an Output File

System_Object_Access_Application_or_API-06-01.jpg 450x301

System_Object_Access_Application_or_API-07-00.jpg 450x295

Figure 5: The Properties Menu Figure 6: Spool File Properties Display

System_Object_Access_Application_or_API-07-01.jpg 450x386



Support MC Press Online

$0.00 Raised:

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: