CCAPrint Newsletter for Model 204 and System 1032 Users

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.

Insight Registration Powered by JDBC for Model 204
By Marie Kelly
Director of Marketing

How do you take one of the world’s fastest and most powerful database systems and put it to good use as the database server for your mission-critical Web applications? By using JDBC for Model 204! The Insight Symposium Registration application shows you just how easy it is to get started.

In past years, when you registered for Insight 204, we accepted your data into a text file, and then copied it into a Model 204 database for management and storage. Even dealing with a relatively small data file, this process was surely inefficient.

JDBC for Model 204 allows programmers to develop Web applications that interact directly with Model 204 databases, thus having a robust, high-capacity database engine powering each and every Web application.

What Is JDBC for Model 204?
Briefly, JDBC for Model 204 is a native type 4 JDBC driver written completely in Java. It is part of Model 204’s Connect* product suite, which provides connectivity to server-based Model 204 data from a client. The JDBC driver supports both User Language and SQL calls to Model 204, so your programmers can use whichever is the preferred access method at your site.

The Insight Symposium Registration Application
Let’s take a look at a simple JDBC for Model 204 example—the Insight Symposium Registration application.

The application is actually a Java servlet running on a Tomcat Apache server. The servlet displays the HTML registration page, which in turn transfers the user’s data back to the servlet with the following code. (http://www.cca-int.com/prodinfo/code.html)

With the user’s data in hand, the servlet is ready to initiate contact with Model 204. The code below shows how the Model 204 JDBC driver is defined and how the connection string is created:

Next, the driver is loaded, the connection to Model 204 is made, and the SQL insert into the Model 204 database is made. This is all accomplished using routines that are defined later in the servlet.

Finally, the servlet sends an e-mail reply to you—the Insight registrant—confirming your registration.

Getting Access to JDBC for Model 204
Ready to get started with your own Java/Model 204 application? If you are an active Model 204 customer, you already have JDBC for Model 204! Beginning with Version 5.1, Model 204 included the Freeway/204 feature, which, among other things, provides free access to all CCA software components required to use the Model 204 JDBC driver for up to four clients. The JDBC driver is on a separate CD. For detailed installation instructions, refer to the JDBC for Model 204 Programmer’s Installation Guide, which you may download from the Documentation Catalog on CCA’s Web site (http://www.cca-int.com/custsupp/documentation/catalog.html).

If you have requirements to run batch processing during normal production hours, but are unable to share files between BATCH204 jobs and production Online jobs, converting your BATCH204 jobs to Online-IODEV=3 threads may be a solution. This can allow multiple dump jobs, for instance, to run concurrently while the Online is processing normal production work. Or, long running reports or even batch updates could run in parallel in the production Online.

Understanding IODEV=3 Threads
An IODEV=3 thread uses Basic Sequential Access Method (BSAM) to read a user’s input stream from a sequential dataset as though that dataset represented an interactive human user. However, the user is actually a sequential dataset. The thread can log in, issue commands and run User Language requests just like a human user. However, when EOF is reached in the sequential dataset, the thread is logged out and no longer available for the duration of the Online. It cannot be restarted and, as shown in the following example, is marked as DEAD in the LOGWHO command.

These threads compete with all other threads--VTAM, SQL, RCL, BATCH2, Horizon, Host Language (CRAM)--for access to memory (servers), I/O (buffers) and CPU. To minimize the effect on Online performance, in most cases, you can assign these threads LOW priority to minimize their competition with other, interactive users. To further minimize their effect, you can require that these threads run in only one server. This is accomplished by arbitrarily setting their table sizes to require a large server, say 800K, and then having only one 800K server defined in the Online environment.

Defining IODEV=3 Threads
The number of IODEV=3 threads that you can define is limited only by NUSERS. These threads can issue any command for which the logged in user has authority. Each IODEV=3 thread requires an input and output dataset. In Figure 1, USER1 and USER2 provide input via a DD * dataset. The third user is providing input via a sequential dataset, DSN=??.

As the input is processed, one line-at-a-time, output is generated; error and informational messages, command output and request output. That output is directed to the output dataset defined for each thread. Output from USER1 is directed to a SYSOUT=* dataset; output from USER2 goes to a DSN=?? dataset; and output from the third user goes to a DD DUMMY dataset.

//IOD3OUT1 DD SYSOUT=*  //IOD3OUT2 DD DSN=??,…   //IOD3OUT3 DD DUMMY
//IOD3IN1  DD *         //IOD3IN2  DD *          //IOD3IN3  DD DSN=??,DISP=SHR
LOGON USER1             LOGIN USER2    
CCA                     CCA
*WAIT FOR DYN ALLOCS    *WAIT FOR PARTS REORG
*SLEEP 60               BEGIN;%X=$WAIT(2);END 
OPEN HISTORY            OPEN PARTS 
DUMP TO DUMPHIST        DUMP TO DUMPPART  
MONITOR FSTAT(HISTORY)  MONITOR FSTAT(PARTS) 
*WAIT FOR REPORTING     OPEN WEATHER    
*SUBSYSTEM (SEE BELOW)  DUMP TO DUMPWEAT 
REPORTING               MONITOR FSTAT(WEATHER)
LOGOUT                  CLOSE ALL  
/*                      LOGOUT
                        /*

Figure 2 shows the corresponding thread definitions in CCAIN:

Figure 2. IODEV=3 thread definitions in CCAIN

//CCAIN   DD  *
NUSERS=24,VTAMNAME=myvtam, . . .
IODEV=3,INPUT=IOD3IN1,OUTPUT=IOD3OUT1
IODEV=3,INPUT=IOD3IN2,OUTPUT=IOD3OUT2
IODEV=3,INPUT=IOD3IN3,OUTPUT=IOD3OUT3
IODEV=7,NOTERM=20,POLLNO=1,DUPTERM=19

Processing IODEV=3 Input Datasets
The input datasets associated with all IODEV=3 threads are opened immediately following Model 204 initialization and processed. If these threads depend on files that are dynamically allocated by another user, they should wait for some period of time for dynamic allocation to complete, as highlighted in Figure 1. If they require that subsystems be started they should wait for those events as well. The threads may also have to wait for other events, which can be accomplished using $WAIT.

Waiting for a Subsystem to Become Available
In Figure 1, USER1 may have to wait for the REPORTING subsystem to start before he can access it. This wait could be accomplished by inserting the request in Figure 3 into the input dataset after the MONITOR FSTAT(HISTORY) command in Figure 1.

Figure 3. Delaying an IODEV=3 thread by waiting for a subsystem

BEGIN
%X = $SUBSYS(‘REPORTING’)
REPEAT WHILE %X NE 1
  PAUSE 10
  %X = $SUBSYS(‘REPORTING’)
END

When the END statement of the request is reached, reading of the input dataset resumes. The REPORTING line will be read and the user will enter the REPORTING subsystem.

Waiting for an ECB to Be Posted
You can also delay an IODEV=3 thread by waiting for an Event Control Block (ECB) to be posted. As with the code in Figure 3, you can add or insert code at any appropriate point in the Figure 1 code.

Figure 4. Delaying an IODEV=3 thread until an ECB is posted

BEGIN
AUDIT ‘WAITING FOR ECB 1 TO BE POSTED’
%X = $WAIT(1)
END

Again, when the END statement of the request is reached, reading of the input dataset resumes. Any user can post ECB 1 with the code shown in Figure 5:

Figure 5. ECB1 posting code

BEGIN
AUDIT ‘USER: ‘ WITH $USERID WITH ‘ POSTING ECB 1’
%X = $POST(1)
END

For additional information on using the code in Figures 4 and 5, see CCAPRINT, June 2003,
“Thread Signaling or $WAIT/$POST Under V5R1.”
For more information on how useful IODEV=3 threads can be, see CCAPRINT editions October 2001 and November 2001.

Summary
If you have a requirement for certain types of processes to run in batch during normal Online production periods, that requirement may be more easily satisified by using IODEV=3 threads as batch processes. IODEV=3 threads can run in parallel, in the Online job, and provide advantages to the serial submission/execution of BATCH204 jobs. The same thing could be accomplished by submitting multiple BATCH2/IFAM2 jobs that login to the Online via IODEV=29 threads, but that involves CRAM overhead and additional job scheduling. IODEV=3 batch processes run in the Online environment sharing files for read and update and avoid file-level locking conflicts that are common with BATCH204 jobs. The processes can be triggered to run at any time during the day, either at scheduled times or as required depending on circumstances and can further assist in providing true 24/7 availability, operational flexibility, and improved throughput.

Back to Basics, Part 6—Text Attribute Formats
By Tym Stegner

This article is the last of a subseries that pertains to constructing attributes. This article completes our discussion of how data is displayed when you extract or report it with the text formats. As with other data types, the FORMAT quality is a string of encoded characters that controls the manner in which that attribute’s data value will be displayed by the WRITE or PRINT commands. You can also override a defined display format within a WRITE or PRINT command, if another display format is temporarily required.

Introducing the A Text Format
The default display for fixed text data types is the A format, which you use when expecting to print out data on one line. The A format syntax is A[width]. Usually, you set a maximum width to include all possible values for the attribute. When you omit the optional width value, you specify a default display width of 20 characters, and the data is treated as Text Varying. More than 20 characters wrap to the following line(s).

If you specify a width, the value is displayed to that width--either by padding with spaces to fill out the width or by truncating the data value, if it is too long.

1032> Variable TXT1 Text Varying
1032> Let TXT1 = "This is a long string that just runs on."
1032> Print TXT1 TXT1 Format A10
        TXT1             TXT1
--------------------  ----------
This is a long        this is a
string that just
runs on.
1032>

The default display format for text varying data types such as the previous TXT1 variable is the AV format. The V option for the A format prevents System 1032 from eliminating trailing spaces during the WRITE command.

1032> Show Attribute FN,MN,LN
Attribute FIRST_NAME Text 20 Keyed
Attribute MIDDLE_NAME Text 20
Attribute LAST_NAME Text 30 Keyed
1032>
1032> Print FN MN LN
     First Name           Middle Name                 Last Name
--------------------  --------------------  ------------------------------
Timothy               J                     Stegner
1032> Write FN MN LN Format (A 1X A 1X A)
Timothy J Stegner
1032> Write FN MN LN Format (AV 1X AV 1X AV)
Timothy              J                    Stegner
1032>

The previous example demonstrates the difference between the Fixed-length Text format A[width] and the A and AV formats. Fixed-length Text formats, when used in the PRINT command, define columns based on the format (and title) width. Using the A format in a WRITE command, however, automatically treats the Fixed-length Text attributes as Text Varying, and truncates the trailing spaces. Also, using the AV format causes System 1032 to not trim the trailing spaces.

Introducing the S Text Formats
The general text format A handles most Fixed-length or small Text Varying data values, but for the longer Text Varying data values, System 1032 has the S text formats.

The S format displays the complete text value within a specified column width by moving (or wrapping) the overflow characters to the following output line, for as many lines as necessary. The two variations for scrolling text formats are: Swidth(format) and SVwidth(format).

The simple S format discards any non-printing characters, as well as stripping duplicate, leading, and trailing spaces. Whereas, the SV format retains all non-printing characters and/or spaces.

For example, consider the following lines of text:

If you store the previous paragraph as an attribute (or variable) of type Text Varying, you can control the display by your choice of S format. (Note although not visible, of course, the last two lines were indented using the tab character.

Bypassing End-of-Line Constraints
Normally, System 1032 does not let you enter data as multiline text, as the first carriage return is taken as end-of-command, which results in a command error for non-termination of the text string. To embed your copy into the text variable, you must make use of a constant specifier.

Constant specifiers exist for all the System 1032 data types. They explicitly declare a data string to be a particular data type. You have used many of the default constant specifiers for text strings, double quotation marks (“text”), and dates, single quotation marks (‘02/10/05’). You can use one of two specifiers for text strings: the quoted string specifier and the delimited string specifier. The delimited text constant specifier in the following example lets you store the multiline string with its special characters, the carriage returns and the tab stops.

1032> Variable PGX Text Varying
1032> Show Variable PGX Format
Variable PGX Text Varying Format AV
1032> Let PGX = #TD/On the shores of the ice-cold lake,
1032_ Where the creature lurked,
1032_   Many of the townspeople crept,
1032_   Hoping for vindication.
1032_ /
1032>

Note: the delimiter used in the previous example is the forward slash (/). Most characters can be used as delimiters, as long as they are not present within the string you are storing.)

The default print format (S20(A)) displays 20 characters per line, wrapping as many lines as are necessary. However, the tabular indents and carriage returns are lost, because the S format suppress non-printing characters.

1032> Print PGX
        PGX
--------------------
On the shores of the
ice-cold lake, Where
the creature lurked,
Many of the
townspeople crept,
Hoping for
vindication.
1032>

In fact, if we included special characters, such as carriage returns and tabs, writing the text out to a single line might display garbled text. In the following example, each carriage return was handled as a simple end-of-line character without wrapping to the next line. Each line of text overwrote the previous line. The result is the fourth line joined to the end of the first line, which was never overwritten.

1032> Print PGX Format A60
                            PGX
------------------------------------------------------------
Where the creature luof the cold lake,
1032>

Only by using the V option of scrolled formats can we display the text in the way we intended. Note the difference between the S and SV formats: The S format strips the non-printing characters from the source text, while the SV format preserves these same characters. Using the SV format, the lines are displayed as entered.

1032> Print PGX Format S38(A) PGX Format SV38(A)
                 PGX                                     PGX
--------------------------------------  --------------------------------------
On the shores of the cold lake,         On the shores of the cold lake,
Where the creature lurked, Many of the  Where the creature lurked,
townspeople crept, Hoping for                   Many of the townspeople crept,
vindication.                                    Hoping for vindication.
1032>

For the Swidth(format) and SVwidth(format) options, width defines the scrolling region (column width) and (format) defines the display format. The format option is usually A, unless you want to truncate the text data value at a pre-determined width. In that case use the An format.

Binary varying formats
A quick word regarding formats for the Binary Varying data type. Binary Varying shares the same default format as the Text Varying data type, SV60(A). As long as the Binary Varying attribute stores text data, the text-related format specifiers work fine. However, Binary Varying attributes can store data that the PRINT nor WRITE commands cannot output, such as audio or picture data. Consider the type of data you plan to store in a Binary Varying attribute before you assign format specifiers for these attributes.

In Summary
These last several articles have looked closely at the components of the attribute definition as determined by the System 1032 data definition language. This series means to help you determine how and why to use the attribute options to configure the fields in your datasets to maximize the usefulness of the dataset in your work.

Coming Attractions
Upcoming topics will deal with the physical creation of the dataset from the attribute definitions, including the use of dataset-related tools, as well as defining a dataset’s relationships to other datasets in databases.


	Insight 204: Insight Registration Powered by JDBC for Model 204
	Model 204: Batch/Parallel Processing Using IODEV=3 Threads	Printer-friendly version
	System 1032: Back to Basics, Part 6—Text Attribute Formats	Printer-friendly version

CCAPRINT: A Newsletter for Model 204^® and System 1032^® Users	February 10, 2005