System 1032 Interactive and Batch Command File Behavior: Part 2
By Tym Stegner
Making Interactive System 1032 Process Errors Like Batch Mode
In CCAPRINT September 2002 we explored the mechanisms from the DCL side of how System 1032 returns errors for interactive and batch job modes. We saw that the DCL components of the jobs worked the same in both environments, but that System 1032 aborted immediately upon errors in batch, while continuing to process past those errors, if run interactively.
We also saw that DCL error handlers via the ON-condition-THEN-statement are the preferred mechanism to respond to unexpected error conditions within the job stream. In this article we will examine the System 1032 error handling capabilities.
System 1032 Error Condition Handling
The primary difficulty of error handling in DCL-based job streams is that the PL1032 commands are generally specified directly within the DCL command file. It is a difficulty because the System 1032 error handling mechanism is procedure-based. To make use of the ON ERROR mechanism, you must specify it as part of a procedure definition.
You can easily make almost any series of PL1032 commands into a System 1032 procedure. Just surround the commands with the PROCEDURE...END_PROCEDURE keywords, in addition to specifying a procedure name. Then, invoke the newly generated procedure using a CALL command.
However, as the commands within a procedure are all compiled before execution, all external references within these commands must be available before the procedure will compile successfully. External references are datasets or libraries referenced by the compiled commands.
Once you make a set of commands into a procedure, you can add the condition handler to the beginning of the new procedure.
Picking Up Where We Left Off
Figure 1 is the sample code from CCAPRINT September 2002:
Figure 1. System 1032 code with a misspelled dataset name
$ SET VERIFY $ ON ERROR THEN GOTO OOPS $ S1032 OPEN DATASET FLIMS IN S1032_DEMO READONLY FIND ALL PRINT ON FILMS.RPT ALL EXIT $! $ DIRECTORY/SIZE FILMS.RPT $ EXIT $! $ZOOPS: !Needed to allow DCL to see the real label $OOPS: $ WRITE SYS$OUTPUT "S1032 Abort occurred, error=",$STATUS $ EXIT
Figure 2 shows the same code with an added procedure A_RPT. The procedure code is bold and highlighted in blue.
Figure 2. Adding procedure A_RPT
$ SET VERIFY $ ON ERROR THEN GOTO OOPS $ S1032 OPEN DATASET FLIMS IN S1032_DEMO READONLY Procedure A_RPT FIND ALL PRINT ON FILMS.RPT ALL End_Procedure EXIT $! $ DIRECTORY/SIZE FILMS.RPT $ EXIT $! $ZOOPS: !Needed to allow DCL to see the real label $OOPS: $ WRITE SYS$OUTPUT "S1032 Abort occurred, error=",$STATUS $ EXIT
Choosing an Error Handler
There are options available for the error handler actions. The error handler in Figure 3 might be used to make a batch job act like an interactive job.
Figure 3. System 1032 error handler
On Error Then Continue Next; End_On
In Figure 3, when the error handler takes control, because of an error in previously compiled commands, it ignores the error and resumes processing at the next command in the procedure. Although not illustrated in Figure 3, you could replace the NEXT option with the RETRY option to reprocess the failed command.
To replicate batch job processing, however, Figure 4 illustrates another approach that is required:
Figure 4. System 1032 error handler that passes error codes
On Error Then Write $ON_STATUS format("***S1032 Error Abort, code %X" h8) Let $STATUS = $ON_STATUS Exit End_On
The error handler in Figure 4 outputs the error code, assigns the error condition that triggered the ON ERROR block to $STATUS and exits System 1032. Combining the code from Figures 2 and 4, the fully executed example in Figure 5 now reads:
Figure 5. A complete error handler
Using the Error Handler Interactively
Figure 6 shows the interactive execution of this error handler procedure:
Figure 6. Executing an error handler interactively
The underlying error, that the dataset is not opened, is not trapped. However, the cause of the procedure problems is that the dataset was not opened. Thus we see that an interactive execution can be made to work like a batch job.
A Different Approach
In the summary from last month's article, I stated there was no easy method to make interactive System 1032 respond to errors as if it were running in batch. This turns out to be not quite true: it is possible to have interactive System 1032 behave exactly like batch. This is done by some small modifications to the System 1032 boot image, S1032.EXE.
S1032.EXE is created from the file BOOT.MAR by the command procedure BOOTBLD.COM, both available from S1032_LIB. Figure 7 shows the concepts of S1032.EXE, an API program:
Figure 7. Conceptual code for BOOTBLD
In batch mode, the DM_ERR call becomes significant: S1032.EXE will set errors to be signaled back to DCL.
To make interactive System 1032 act like batch, it was possible to modify BOOT.MAR to execute batch mode processing while in interactive mode. A copy of the modified source, as well as a modified build command file, is available for download from the CCAPRINT subdirectory on the System 1032 FTP Server. The address is:
FOX.CCA-INT.COM
Choosing Your Operating Approach
You might think: "I'll just use the S1032EX image, and not worry about changing my working code around so much." This may indeed work well for your environment.
However, image activation is not an inexpensive operation. It may be that for the purposes of your batch/interactive job requirements that starting and stopping System 1032 many times is more expensive than coding the PL1032 to respond to error conditions.
Only you can make this decision, based on your environment and requirements. It involves balancing coding additional or better DCL error handling against coding System 1032 condition handlers.
Insight 204 Insight 204 Sheds Light on V5R1, JDBC, Analytics By Marie Kelly
More than 100 Model 204 users and experts gathered on Boston’s waterfront for this year’s Insight 204 Symposium. And while the views of Boston from the Harborside Hyatt were spectacular, it was the glimpses of the newer product releases that captivated the attendees and justified the trip.
Earlier this year, CCA unveiled several new product releases and tools, including Model 204 V5R1, Connect* V5R1 (with its new component JDBC for Model 204), and CCA Analytics V2R1. Each of these new capabilities were explored in detail at Insight 204, leaving attendees excited and prepared to upgrade to the new version of Model 204, and implement new solutions requiring connectivity and business intelligence functions.
Model 204 V5R1
The latest version of Model 204 was clearly the headline of the symposium, because it is faster, more powerful, and more cost effective to run than ever before. New features that were discussed in detail by Model 204 experts and consultants included
If you have not yet received the new release of Model 204 V5R1 and would like to get started immediately with the new features, please fill out a software upgrade form on CCA’s Web site at http://www.cca-int.com/forms/upform.html.
New Connectivity Solutions
With the Model 204 database engine getting faster and more powerful with each release, the need and desire to access it from other platforms and environments grows stronger each day. This was evident by the large number of customers who cited this as the most important topic they learned about at Insight 204.
This year, CCA introduced a new version of Connect* that is not only multi-threaded, but also provides support for a native Java interface to Model 204 called JDBC for Model 204. With this new utility, you can connect just about ANY client platform to Model 204, as long as it is Java-enabled. This extends the world of Model 204 connectivity to include Unix™ and Linux™ platforms, Palm™ and cellular devices, and many others. So you can develop applications for the Web, for wireless access, or for countless other platforms and purposes, and leverage the information and access speeds provided by your Model 204 databases.
In addition to supporting JDBC, the new version of Connect* includes enhancements for the ODBC API, as well as network performance. For more information about JDBC for Model 204, Connect*, and other connectivity options, please contact your Account Representative, or contact the CCA corporate office at (508) 270-6666.
CCA Analytics V2R1
With a new version of CCA Analytics released this year, there’s no better time to begin harvesting the fruit of your corporate data, by implementing a business intelligence solution with CCA Analytics.
Presentations and demonstrations at Insight 204 showed Model 204 users how they could use CCA Analytics to transform raw data into business information that enabled better decision-making. New features include improved administration dialogues and security features, and the ability to share object stores so you can collaborate with your colleagues in workgroups. For more information about CCA Analytics, please contact your Account Representative, or contact the CCA corporate office at (508) 270-6666.
Product Futures
While this year’s Insight 204 Symposium was largely about the latest releases, it also took time to discuss subsequent releases, and the importance of the product planning process to ensure that your future needs are met.
While the early results of the 2002 Model 204 Customer Survey were presented at Insight 204, it is not too late to ensure your organization’s needs are considered in future releases.
Customer and Partner Participation
Finally, Insight 204 was not only a great venue for learning about what CCA is doing, but what our customers and partners are doing with Model 204 as well. CCA’s sessions were nicely complimented by 11 additional presentations from customers and partners including Centrelink, Calgary Police Service, Foodland, Marks & Spencer, Moonbrook Hill Consulting, IBM, Sirius Software, Information Technology Systems, Nodus Inc., and Yoda Software. We are grateful for their participation, which contributed greatly to the overall success of the symposium, and we hope to hear from more of you at the next Insight 204!
More Insight 204 Information
For more information about what transpired at Insight 204, and to view the entire symposium photo album, visit www.cca-int.com/usergroups/insight/main.html. If you were unable to join us this year, we sincerely hope to see you at the next Insight 204 Symposium!
Model 204 Extending the Power: Introduction to JDBC for Model 204
By Steve Nelson Connectivity within our Model 204 community continues to grow. As the demand for Web-enabled services become increasingly popular, providing a robust, cross-platform access to Model 204 has become a necessity in our arsenal of connectivity products.
An increasing need for our customers was to have access from any platform. This led us to the decision to use Java. Java, not only gives us the ability to Write Once, Run Anywhere, it also provides the ability to develop a driver with easy integration to other platforms and Web services. This new connectivity option, an extension of our Connect* product suite, is called JDBC for Model 204.
JDBC for Model 204 is a native Java driver (type 4) built to the JDBC 2.0 specifications. It provides SQL and User Language (RCL) capabilities. The JDBC driver is object oriented by design and provides a robust network transport to Model 204 via the JDBC API. It encourages access to Model 204 from Web Servers, Applets, GUI Applications, or Servlets on any supported operating system. These operating systems include Linux, Unix, OpenVMS, z/OS, z/VM and so on.
In this two-part article we will examine the uses of Connect* JDBC for Model 204 and provide examples with tips and tricks using Java and JDBC.
Extending the Power: Highlighting JDBC, Part 1
By Mark LaRocca
The CCA Insight 204 Registration System: A JAVA Client/Server application using the Model 204 JDBC Driver—and it is all free!
This was the mantra at the JDBC for Model 204 presentation at the recent Insight 204 Symposium and, you know what? It’s actually true. For Insight 204, I designed and wrote a Java application called Reg.java to automate our customer registration for the symposium.
Freeway/204
First let me explain about the free part. Introduced with Model 204 V5R1 is Freeway/204. Freeway/204 provides all sites with free access to Connect* and Horizon. This software is fully functional though limited to the number of simultaneous users. With this free access you can use either ODBC or JDBC to access data. Let's make full use of the new JDBC for Model 204 feature next!
Proposing a Registration Application
To cut down the lines at the opening day registration table, we entered preregistered guests into the Register table prior to Insight 204 using Reg.java. First, a bar code was assigned to each guest. A bar code reader was swiped across the code, which read the bar code into a record. The remaining information for the record was typed in.
At Insight 204 as preregistered guests checked in with us, they were given badges with their name and bar code. Our registration staff swiped the bar code into the registration PC. The identification number would appear in the Registration ID box at the top of the page, as shown in Figure A.
At the same time the other preregistration information appeared on the screen. The button changed from SAVE to UPDATE, and we could enter new information, such as, what classes the customer wanted to attend, and what they wanted for lunch on Wednesday.
If the customer was not preregistered, a bar code was assigned and swiped into the PC on the spot. After additional information was entered, the record was added to the Register table by pressing the SAVE button at the bottom of the page.
Figure A. Sample display screen with registration data
Acquiring Building Tools
When I started building the Reg.java application, the first thing I needed was a good development tool. So, I downloaded Jcreator LE (http://www.jcreator.com) for free. Yes, it’s a limited edition IDE; but, it is all I needed. If you want the full-blown version, it is available and inexpensive.
I had already installed the Java SDK 1.3.1 and JRE, which are available from the Sun Java Developer site (http://java.sun.com/) and are also free. There are plenty of free examples of code at this site as well.
Best of all, JDBC for Model 204 is absolutely free when you install Model 204 V5.1.0. By the way, the CCA Java driver also works with Model 204 V4.2.0. However, you must have Horizon TCP installed. In Version 5.1.0, Horizon is automatically installed.
Now, let me show you how easy it is to use the CCA JDBC driver to access Model 204 data and point out some interesting code in Reg.java.
Working Guidelines
The first mandate was: Keep it simple. No more than one button. No more than one page.
My second mandate was to write the system using Java classes. The application is backed by 14 classes, all rolled into our program, Reg.java. At Insight 204 we distributed a CD of sample code. If you would like one, drop us an e-mail message so we can send it to you.
Finally, I was asked to make it bullet proof and impervious to user errors.
Making the Connection
As shown in Figure B, Menu has a Connect option, which presents the user with the dialog box in Figure C.
Figure B. Insight 204 Registration dialog box
Usually, end-users are not asked to enter the entire URL, as shown in Figure C, because of potential typing errors. Instead, they supply their name and password, which the programmer plugs into the URL. However, I wanted to make things flexible and give CCA staff the option to change a port number and the IP, if necessary.
Figure C. The Connect option dialog box
Clicking Enter connects to an Online running on our OS/390 system that is using port 2500 in its link definition. The Java code to make the connection is shown in Figure D.
Figure D. Java code that makes the connection to Model 204
. . . import com.cca.j204.*; //import Model 204 JDBC driver classes . . .
public void connectdb(String urlIn) { setCursor( Cursor.getPredefinedCursor(Cursor.WAIT_CURSOR ) ); try {
url = urlIn.trim(); Class.forName( "com.cca.j204.J204Driver" ); //load the driver try { dbconn = DriverManager.getConnection( url ); // connect using URL entered by user }
The blue, bold lines in Figure D show the necessary code to connect to Model 204. Errors are reported to the user by displaying messages under the button on the page. Reminder: the variable url, in this case, is equal to
JDBC:J204://CCAMVS1:2500/SQL/MARK/MARK
Setting Up the Mainframe
Just to give you some idea of what is necessary on the mainframe side, here are the link, processgroup, and process definitions, which are in the Model 204 Online at port 2500 to which the previous URL will connect.
Figure E. Model 204 DEFINE command on the mainframe
DEFINE LINK LINKTCP WITH SCOPE=SYSTEM TRANSPORT=TCPSE - PROTOCOL=IP CONNECTIONS=6 INBUFSIZE=4096 LOCALID=ANY - SERVPORT=2500
DEFINE PROCESSGROUP T1 WITH SCOPE=SYSTEM LINK=LINKTCP - REMOTEID=000.000.000.000 INLIMIT=5 MASK=000.000.000.000 - LOGIN=NOTRUST GUESTUSER=REJECT . . . DEFINE PROCESS CCARSQL WITH SCOPE=SYSTEM DATALEN=32752 - FROM=(T1,T2,T3,T4,T5,T6,R1,SQLUSER)
The SERVPORT=2500 specifies the TCP port over which this link will communicate. You can get a SERVPORT value from your TCP administrator. LOCALID= can be set to the IP address of your OS/390 system, or you can specify ANY, if you want Model 204 to automatically use the IP address of the OS/390 system.
Don't forget to specify your processgroup name in the FROM= of the DEFINE PROCESS command. See your Model 204 SQL Connectivity Guide and Model 204 Command Reference Manual for details about the DEFINE commands.
Using the Registration System
When the connection is successful, you can begin using the system. In Figure A, notice that once a record is entered, the button is UPDATE. The code to display the Customer's Registration record is shown in Figure F.
Basically, the code passes a query to Model 204 based on the Registration ID scanned. If the record is found, the program code passes the record set to the display process for formatting to the page. The relevant lines of code are bold and highlighted blue.
Figure F. Code to display a Customer's Registration record
. . . try { if ( !screenvar.id.getText().equals( "" ) ) { Statement statement = dbconn.createStatement(); //create the stmt for query String query="SELECT * FROM reg.register "+"WHERE regid='" + screenvar.id.getText() + "'"; ResultSet rs = statement.executeQuery( query ); //execute the query display( rs ); //pass the resultset to the display method if (displaySuccess) { msgLabel.setText("Registration record found" ); buttonIn.setText("Update"); } . . . // Display results of query public void display( ResultSet rs ) { displaySuccess = false; try { if ( rs.next() ) { displaySuccess = true;
//set the value of the screen variable //to the column value of the row //for all columns in the row returned screenvar.id.setText( rs.getString( "regid" ).trim() ); screenvar.company.setText( rs.getString( "co_cd" ).trim() ); . . . // display all screen data here; // code deleted to save space } . . .
The Insert and Update routines work much the same way as the Find.
Handling Single Quotation Marks
A problem occurred when I tried to enter a single quotation mark in the Notes field. I was simply concatenating an Update statement and putting any values entered into the statement; but, of course, these values must be between quotation marks. Figure G illustrates the Update statement from the UpdateRecord class.
Figure G. Update statement from UpdateRecord class
QuoteValid st = new QuoteValid(screenvar.notes.getText()); NotesOut = st.getValidQuoteText() + " "; String query = "UPDATE reg.register SET " + "title = '" + screenvar.salutation.getText() + " ', fname = '" + screenvar.first.getText() + " ', lname = '" + screenvar.last.getText() + " ', addr1 = '" + screenvar.address.getText() + " ', addr2 = '" + screenvar.address2.getText() + " ', addr3 = '" + screenvar.address3.getText() + " ', city = '" + screenvar.city.getText() + " ', state = '" + screenvar.state.getText() + " ', zip = '" + screenvar.zip.getText() + " ', country = '" + screenvar.country.getText() + " ', email = '" + screenvar.email.getText() + " ', phone = '" + screenvar.phone.getText() + " ', ext = '" + screenvar.ext.getText() + " ', fax = '" + screenvar.fax.getText() + " ', co_cd = '" + screenvar.company.getText() + " ', notes = '" + NotesOut + " ', checked_in = '" + checkedIn + " ', morning_session = '" + morningSession + " ', afternoon_session = '" + afternoonSession + " ', questions = '" + questionaire + " ', dinner = '" + dinnerIn + " ' WHERE regid='" + screenvar.id.getText() +"'";
I found that if I entered a single quotation mark within the Notes field, for example, "it's", the statement returned an SQL syntax error from Model 204. For example:
UPDATE reg.register SET notes = ' it's a great day '
A single quotation mark is evaluated as the end of the text, not as part of the text to be inserted. To resolve this issue, I wrote a special class, QuoteValid, which analyzes entered text and replaces all single quotation marks with two single quotation marks. Two consecutive single quotation marks are replaced and stored in the text field as a single quote. The first two lines of the source code in Figure G pass the previous UPDATE code through the QuoteValid routine and change it to:
UPDATE reg.register SET notes = ' it' 's a great day '
This compiles properly. Because it was written as a class, QuoteValid can be moved to any directory and used to edit any text you wish. This demonstrates the advantage of writing code in classes.
Closing Connections
Don't forget to close your connections to Model 204 when you are done. Often end-users walk away or minimize screens. I try to close statements and connections whenever I encounter problems or when the transaction completes. If you don't do this, you may see open threads and end-users logged on to Model 204, who are basically idle. You can run out of threads, if your application users do this often enough. Closing connections is as simple as:
statement.close; dbconn.close();
And don't forget to put it in a Try/Catch block, or you may get some unexpected SQL errors if the connection is already closed.
Development Timeline
How long did this project take? The basic application was written and working in about four days. Changes and testing took another week; the final beautification took a day. Including design, back to front, the application took about 14 working days, or three weeks. I did not do badly for an amateur. There is only one underlying Model 204 file that is mapped to schema Reg and table Register.
Conclusion
I hope you can see how easy it is to use Java and the new Model 204 JDBC Driver. I also hope this gives you some ideas and a desire to install it and get started. Oh, did I mention it's all free!! Good luck.
Coming attractions
In Extending the Power: Highlighting JDBC, Part 2, we will discuss our Web-based CD ordering system, which was also hard at work at Insight 204. This system has three additional files in schema Reg mapped to the tables: Orders, Products, and Comments.
Copyright © 2008 Computer Corporation of America. All right reserved. Published in the United States of America.
Contact CCA Webmaster Copyright 2008
