Model 204 USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.
Writing $Functions with Your Own Error Messages By James Damon
In the February 2009 issue of CCAPRINT, I showed you how to write your own $function in IBM Assembly Language, assemble that $function in the FUNU control section, and link-edit FUNU into the Model 204 nucleus using ONLINE or BATCH204 load modules. Once that is done, you can call your $function from User Language to perform special processing. The example I provided, $INSCHAR, however, was incomplete. It had no error detection or error reporting facilities to indicate to the user that an input value to the $function was incorrect. In this article I will show you how to add your own error messages to the MSGU control section, then assemble and link-edit that control section into the Model 204 nucleus.
MSGU Control Section As with the source listing for the FUNU control section, the MSGU control section is also found in MACLIB, which is distributed with each release on the Model 204 installation tape. It is probably named something like M204.rlse.MACLIB, where rlse=V710, V610 or V510. I will not reprint the entire source listing for MSGU here, just the part that involves defining user error messages:
ESTRT USER=YES,PREFIX=USER* REPLACE THIS DUMMY MESSAGE WITH ONE OR MORE USER MESSAGES EDEF 1,0000,I,,,'DUMMY MESSAGE' **********
For the $INSCHAR function, I’ve added the following two error messages (in blue):
ESTRT USER=YES,PREFIX=USER* REPLACE THIS DUMMY MESSAGE WITH ONE OR MORE USER MESSAGES EDEF 1,0000,I,,,’String length must equal 10 bytes’ EDEF 2,0000,I,,,’String must be numeric 0-9’
In the $INSCHAR source listing, I have added code to test the string argument to enforce those two rules:
The Modified $INSCHAR Code The blue lines of code below were added to implement error checking.
**$INSCHAR Receives a numeric character string (ARG1) of length 10 * and returns that character string with the single * character (ARG2) inserted in col 4 and col 7 of ARG1.* Col: 4 7* | |* v v* ARG1: 1234567890* ARG2: _ (DEFAULT) ** RETURN: 123_456_7890$INSCHAR ENTER MVC BUF2(1),INSDEFC Get default character for insert ARG 2,NOARG=INSDEF If ARG2 not provided, use default L R2,4(X1) Type of ARG - required for RTSTRL CCALL RTSTRL Call ReTurn STRing with Length* Returns A(ARG2)-1 in R1 and len in R2 MVC BUF2(1),1(R1) Move ARG2 (char for insert) to BUF2INSDEF ARG 1,NOARG=INSDONE If ARG1 not provided, return null L R2,4(X1) Type of ARG - required for RTSTRL CCALL RTSTRL Returns A(ARG1)-1 in R1 and len in R2 C R2,=F'10' Is length of ARG1 exactly 10 bytes? BNE INSERR1 No, issue error* Ensure ARG1 is numeric only MVC BUF1(10),1(R1) Move ARG1 to BUF1 L X1,KAPFF A(KZFF) = 256 foxes MVC KAJUNK(256),0(X1) Setup table for Translate and Test MVC KAJUNK+C'0'(C'9'-C'0'+1),KA00 Get zeroes for numbers BCTR R2,0 Subtract one from length EX R2,$INSNUM TRT BUF1(0),KAJUNK IF BNZ If non-numeric character found ERROR 2,OPT=USER String must be numeric 0-9 B INSDONE Set len of ret string to 0 and return IFEND LA R2,10 Get len back in R2 MVC BUF1(20),KA00 Clear BUF1 MVC BUF1(3),1(R1) Move 1st 3 chars of ARG1 to BUF1 MVC BUF1+3(1),BUF2 Insert ARG2 MVC BUF1+4(3),4(R1) Move next 3 chars of ARG1 to BUF1 MVC BUF1+7(1),BUF2 Insert ARG2 S R2,=F'6' Subtract (3+3) bytes from ARG1 length EX R2,$INSMVC Move rest of ARG1 to BUF1 A R2,=F'8' Get new len of ARG1(6+2+rest of ARG1) LA R1,BUF1-1 Get A(BUF1) minus 1 B INSRETINSERR1 ERROR 1,OPT=USER String length must be 10 bytesINSDONE SR R2,R2 No ARG1, set return string len to 0INSRET LEAVESTR Return the new string or nullINSDEFC DC C'_' Default character for insert$INSNUM TRT BUF1(0),KAJUNK TRT to detect non-numeric data$INSMVC MVC BUF1+8(0),7(R1) Remainder of ARG1 starting column 7 LTORG EJECT
Assemble and Link-Edit Both FUNU and MSGU After you have updated the FUNU and MSGU source listings in the Model 204 macro library, M204.rlse.MACLIB, you can use the FUNUASM and MSGUASM jobs in the JCLLIB dataset to reassemble those control sections and place the new object decks in M204.rlse.OBJLIB. Remember, however, that you must set these options to ‘Y’ in INSPARMS during the installation process, or the FUNUASM and MSGUASM jobs will not be created:
FUNC-USER=Y ** Enable USER-WRITTEN functionsMSG-USER=Y ** Enable USER-WRITTEN messages
Following successful assembly, the M204RLNK or similar job can be used to link those two control sections from M204.rlse.OBJLIB into the ONLINE and BATCH204 load modules.
Testing $INSCHAR The following examples show the results with the error checking code and the new error messages assembled into MSGU. In the first example the procedure supplies the telephone number to $INSCHAR as a literal.
BEGINPRINT $INSCHAR('7814666601','.')ENDINCLUDE 0781.466.6601
In this next example the procedure retrieves three telephone numbers from three different records in a Model 204 database and passes them to $INSCHAR from the field TELNO.
BEGIN FR WHERE TELNO IS LIKE * PRINT PRINT TELNO PRINT $INSCHAR(TELNO,'-')ENDINCLUDE 0 800755422*** USER.0001: String length must equal 10 bytes 3037868%62*** USER.0002: String must be numeric 0-9 8005551212800-555-1212
MSGCTL Command for User Messages The MSGCTL command can be used to change the default action taken when a user-defined message is issued just as it can be used to change that action for Model 204 defined messages. If you need a CCASNAP to be generated when one of your error messages is issued, you may want to use the MSGCTL command like this:
MSGCTL USER.0001 SNAPPDL
See the description of the MSGCTL command in the Model 204 Parameter and Command Reference for further details.
Summary Without error checking we really did not have a useful $function. Now that we have added the appropriate error messages and error checking code, we have a complete $function. It inserts a separator into a character string of numbers and it also can detect and report errors in that string.
Insight 204 USE OF AND ACCESS TO PRODUCTS AND FEATURES ARE IN ACCORDANCE WITH THE TERMS AND CONDITIONS OF THE USER’S SOFTWARE LICENSE. THE PRESENTATION OF MATERIAL HEREIN DOES NOT, IN ANY MANNER, MODIFY SUCH TERMS AND CONDITIONS.
Connectivity By Steve Nelson
Connect✭ for the Microsoft .NET Framework CCA announced the availability of Version 7 Release 1 of Model 204 on March 31, 2009. What is especially new and exciting is an addition to our Connect✭ Suite of products, the connectivity driver for the Microsoft .NET Framework. This addition to the Model 204 product line gives you many different connectivity options that enhance the end user experience. Our connectivity options are plentiful, from our $SOCKET User Language function to our MQ/204 interface to our Connect✭ Suite. CCA has all the necessary tools to provide robust client/server solutions.
With CCA’s newest driver, we bring a completely new client/server offering to our customers, who use the Microsoft Visual Studio development environment for Windows. This new driver provides Windows developers with a direct API to any Model 204 Online. The Connect✭ for .NET client/server API has a complete set of methods and its own namespace to integrate into any web or GUI application using the .NET Framework.
Compatibility This .NET driver is .NET 2.0 compatible and follows the strict development API set forth by Microsoft .NET Framework guidelines.
Development Tools To take advantage of this new driver, copies of Connect✭ for .NET Framework and Microsoft Visual Studio 2005 or 2008 are required. Also, the SQL engine and Horizon TCP/IP listener must be installed and running on Model 204 to complete the connection using the Connect✭ for .NET driver.
How to Use the Connect✭ for .NET Driver Install the Connect✭ for .NET Framework that is included and documented in your Model 204 V7R1.0 shipment. When the installation is complete, start Microsoft Visual Studio and create a Windows Application. I used the C# language for this demonstration. Feel free to use another language of your choice.
Once the project has a name, right click on References and add Connect✭ for .NET to the project.
In the following Add Reference dialog box click the Browse tab and navigate the Look in: text box to:
C:\Program Files\CCA\Connect Star for Model 204\.NET
Select CCA.Data.dll, the driver, and click OK.
After you make the selection you can see CCA.Data in the References folder of your project.
You are now ready to use the driver and its native namespace API in this application.
Using the CCA.Data Namespace API In the Connect✭ for .NET folder you will find a help file that explains the API and how to use it with different Microsoft Visual Studio languages. The reference can be found in:
C:\Program Files\CCA\Connect Star for Model 204\.NET\CCA.Data.chm
An additional help file is available that demonstrates and explains the connect string options and provides examples on how to use the Connect✭ for .NET Framework driver. You can find all of this information under Windows menu:
Programs > Connect Star from Model 204
Demonstrating a Connect✭ for .NET Framework Application After you add the Connect✭ for .NET driver to the project, you can begin to use the API. In my example, I created a form with four components. The object of this demonstration is to pass an SQL statement to the API, so the API will fetch the data and populate a data view grid.
The first component built is a label that simply has SQL Statement as its text property. For the second component I added a text box called textBox1. I will use this component to pass the SQL string to the command API. For the third component, I added a button that will be used to execute the statement and populate the data view grid, which is the fourth component. The data view grid component is called dataGridView1. The following is a picture of the final form.
By right clicking on the form design and selecting the "View Code" option, you can begin entering the code below. At the top of the form's code, place the CCA.Data namespace reference into the code. Use the example below.
// Get CCA.Data namespace using CCA.Data.Model204Client; ← CCA.Data Namespace. Add this to your code
At this point, lets go back to the form design and double click on the button component. This creates the button's action. Add this simple code segment to the button's action.
String sqlStatement = textBox1.Text; // Get the String from the text box try { string connectString = "datasource=mymainframe:5555;uid=myuid;pwd=mypwd;" _ Change this + "connectiontype=sql;"; // Your Connect String to Model 204 _ Connection String // Create an instance of CdmSqlDbConnection using the connection stringCdmSqlDbConnection connection = new CdmSqlDbConnection(connectString); // Open the connectionconnection.Open(); // Create an instance of CdmDbDataAdapter using the connection string // and the SQL StringCdmDbDataAdapter cda = new CdmDbDataAdapter(sqlStatement, connection); // Create an instance of the standard DataTable (Microsoft specific)// Note: See System.DataSystem.Data.DataTable dt = new System.Data.DataTable(); // Fill the Data Tablecda.Fill(dt); // Tell the dataGridView1 to use the newly filled Data TabledataGridView1.DataSource = dt; // Refresh and Show the new DataGriddataGridView1.Refresh(); // Close the connectionconnection.Close(); } catch(Exception exp) { Console.WriteLine("Exception caught: '{0}'", exp);}
The previous coding example will connect to Model 204 using SQL and populate the dataGridView1 component. By simply adding this code into the button's action, you are able retrieve data from Model 204 and place the row and column data into the data view grid. Your component names and connection string may vary, but the concepts are still the same.
Now, let’s make the connection and pass along the SQL string to Model 204. Start the application and enter an SQL statement.
The SQL statement entered is common to the SQL engine and is a good example of the tables available to a user.
Now, press the button component for the results.
As you can see the SQL statement has successfully returned the results and populated the data grid. Although this is a simple example, it should help demonstrate our newest addition to the Connect✭ Suite.
In Summary It is very simple to access Model 204 data using Microsoft Visual Studio. Your applications will be more sophisticated, but we hope this helps demonstrate how simple access to Model 204 can be. In the next issue of CCAPRINT, we will demonstrate User Language access using the new Connect✭ for .NET driver.
Visit our web site to learn more about the Connect✭ Suite of products you should attend the CCA Insight 204 Symposium being held June 7-10, 2009 in Boston.
You can attend the Breakout Session ‘Getting Connected to Model 204’ and register for the training workshop ‘Mastering connectivity with Model 204’ both of which will help you implement and integrate our connectivity options at your site.
Sirius Software Joins CCA at Insight 204
In addition to learning all about V7R1 of Model 204, this year's Insight 204 Symposium is the best place to learn what's new from Sirius Software as well!
In recognition of the current economic environment and reduced travel and training budgets, Sirius Software will not hold a separate user group meeting in 2009, but rather will be partnering with CCA at this year's Insight 204 Symposium being held in Boston on June 7-10, 2009. Both companies believe the combined conference will ensure the most valuable and cost-effective experience for all Model 204 customers. We hope you are planning to join us in June for this FREE educational opportunity.
For a list of planned CCA and Sirius presentations, visit the Breakout Sessions page on the Insight 204 Web site. Also, there are a number of Training Sessions being offered, and enrollment in those sessions is limited! So please Register as soon as possible to be assured of admission into the classes of your choice.
Lodging Deadline Fast Approaching! The deadline for the guaranteed hotel rate of $215 per night is April 30, 2009. If you are planning to attend Insight 204 but have not yet made your hotel reservation, you should do so immediately by contacting the Hyatt directly. Be sure to let them know you are attending the Computer Corporation of America event.
More Insight 204 InformationIf you have any questions about Insight 204, please complete and submit this Feedback Form. We look forward to seeing you in Boston in June!
Copyright © 2009 Computer Corporation of America. All right reserved. Published in the United States of America.
