MC Press Online

Color by Numbers with DSM

Contributed by Gene Gaunt Wednesday, 30 June 1999 Last Updated Wednesday, 30 June 1999

Splash some color on your 5250 canvas with DSM -- and your imagination!

If you have written screen programs on the AS/400 using DDS and SDA, you have probably discovered that you cant abut changes in colors and attributes. Thats because DDS and SDA need spaces between fields for hidden 5250 display attributes. A 5250 display attribute casts the field it precedes into a color (blue, green, turquoise, red, pink, yellow, or white) with attributes (separator, blink, underline, highlight, reverse, normal, or nondisplay).

When I lay out a crowded screen with DDS and SDA, sooner or later I succumb to the fact that 5250 display attributes occupy valuable real estate. Wouldnt it be nice if you didnt have to waste spaces on the screen just to change colors and attributes? Well, there is a little-known programming technique on the AS/400 that can adjoin color and attribute changes with no intervening blanks. Moreover, this technique provides seven more screen colors than are available with DDS for a total of 14 colors. All you need to make this technique work is a workstation attached to a controller supporting the Enhanced Non- Programmable Terminal User Interface (ENPTUI) and an ILE compiler to create a program.

The trick is to call a program that sends Write Extended Attribute (WEA) orders to the ILE Dynamic Screen Manager (DSM) through the Write Data (QsnWrtDta) API. The DSM lets you do things with screens that you cant do with DDS and SDA, such as define screen colors and attributes with WEA orders instead of 5250 display attributes.

Wild and Wacky Colors

The DSM is a large set of bindable APIs that offer an alternative to DDS. Similar to the way CGI programs let you build dynamic HTML screens, the DSM APIs let you assemble strings of 5250 commands, orders, and attributes on the fly to construct screen I/O. This article focuses on the DSM API QsnWrtDta. Figure 1 lists the 12 parameters you need to make a bound procedure call to QsnWrtDta.

Before I explain WEA orders in detail, I should give you an example of WEA orders in action. Figure 2 is a short ILE CL program, TESTWEA, that sends several WEA orders to the QsnWrtDta API. Compile this program with Create Bound CL Program (CRTBNDCL) and specify DFTACTGRP(*NO). On a display station attached to an ENPTUI-capable workstation controller, run the program with CALL TESTWEA. Figure 3 shows you what you will see. You can study the colors in Figure 3 and cross-reference them to the field-level comments in Figure 2. Note the following:

Row 1 contains the word COMPANY. Each letter is a different color. The yellow and turquoise are just yellow and turquoise, with no column separator attribute.

Row 3 contains the word invoice with the letter v underlined. Row 5 is an input field for a U.S. Social Security number. Three bytes are red, 2 bytes are white, and 4 bytes are blue. No blanks occur between colors, and the entire field is 9 bytes long. The cursor changes color as it moves across the input field. The Insert and Delete keys shift numbers in the input field but do not shift colors.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 04:31

MC Press Online

By now, your mind may be spinning as you think of all the things you can do with WEA orders to spruce up your greenscreen applications. With WEA orders, all of the following are possible on 5250 workstations:

Drawing a reverse-image checkerboard or game Building a toolbox palette to resemble a Java Integrated Development Environment Embedding mnemonic underlines or blinkers into the middle of words Showing each letter of your company name in a different color Dividing input fields into zones of alternating colors Overlaying columns of subfile data with vertical bands of color

How to Use WEA Orders

WEA orders work only with ENPTUI-capable workstation controllers and update the Extended Character Buffer (ECB), a secondary plane of attributes within the ENPTUI architecture that take precedence over 5250 display attributes. Consequently, if you send a WEA order and 5250 display attribute to the same screen location, the WEA order presides.

IBM added the ENPTUI to OS/400 in V2R2 to support graphical constructs, such as check boxes and pull-down windows, and then created new DDS keywords to generate most ENPTUI commands and orders. However, IBM provided no new keywords for WEA orders. The only way to access WEA orders is through a user-defined record system such as the DSM, not DDS.

WEA orders are simple to generate. There are two kinds of WEA orders: extended attribute and extended color. To create an extended attribute, enter X'1201nn' into the first parameter of QsnWrtDta. Figure 4 lists the choices for extended attributes. The third byte denotes which attribute you want. To create an extended color, enter X'1203nn' into the first parameter of QsnWrtDta. Figure 5 lists the choices for extended colors. As with the attributes, the third byte denotes the color you want. There are 14 colors available: primary and secondary shades of blue, green, turquoise, red, pink, yellow, or white. On some terminals, the secondary shades map into the primary shades.

When the third byte in a WEA order is X'80', the workstation controller turns off the WEA order attribute or color that was in effect up to that location and resumes the 5250 display attribute background. Figure 6 lists the choices for 5250 display attributes.

WEA orders do not increment the current display address. In 5250 parlance, the current display address is where the workstation controller writes the next byte. Note that this behavior is different from 5250 display attributes and regular text, which do increment the current display address, implying that, if you want to write multiple WEA orders across the screen, you need to call QsnWrtDta multiple times, one call for each WEA order. There is one exception to this rule, however. You can write an extended attribute and extended color to the same location by using one 6-byte string in the first parameter of QsnWrtDta. My TESTWEA program does that twice.

Before an interactive program uses a WEA order for the first time, its a good idea for the program to test whether the workstation can handle WEA orders. If it cant, the program should offer some graceful alternative or exit. If you attempt to write a WEA order to a workstation not attached to an ENPTUI-capable controller, you see a cryptic 1005012D negative response code message and the job ends. A program can use the Query 5250 (QsnQry5250) API to retrieve a flag indicating whether the workstation is

(IDE)
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 04:31

MC Press Online

WEA-capable. If QsnQry5250s return variable byte 53 bit 5 is on, the workstation is WEA-capable.

Screen Art

In addition to TESTWEA, Ive included on the Web an RPG IV program that I call PAINT because it lets you paint a 5250 workstation into 24 x 80 pixels of color. To download this program, please see the MC Web site at www.midrangecomputing.com/ mc/99/07. Compile the PAINT program with the Create Bound RPG Program (CRTBNDRPG) command and specify DFTACTGRP(*NO). Then, make a photocopy of Figure 7, cut it out, and place the strip of paper above the function keys on your workstation keyboard. Then, run the following Create Data Area (CRTDTAARA) command to create data area CANVAS: On a color terminal, run the program with CALL PAINT. At first, you see a blank screen. Position the cursor anywhere, and press F1 to paint one little pixel of blue. Move the cursor, and press F2 to paint a pixel of green. Move the cursor, and press F3 to paint a pixel of turquoise. Continue moving the cursor around the screen, pressing F1 through F7 to paint pixels of color. You can completely abut pixels of different colors.

Use F13 through F19 (the upper Shift of F1 through F7, respectively) to paint the seven secondary colors (if they are available on your display station). Use F8 to erase pixels. When you are finished, press F12 to exit the program and archive your painting into the CANVAS data area.

The next time the muse strikes and you decide to use PAINT, the program retrieves your painting from the CANVAS data area. You can then continue moving the cursor around, pressing more function keys and painting more things into your masterpiece. This technique reminds me of the pointillistic style of Georges Seurat in A Sunday Afternoon on the Island of La Grande Jatte. From a distance, the La Grand Jatte dots merge to appear as if they were people with parasols at a picnic. Now, you can use this technique to create your own type of art.

1 Data INPUT CHAR(*) 2 Data length INPUT BINARY(4) 3 Field ID INPUT BINARY(4) 4 Row INPUT BINARY(4) 5 Column INPUT BINARY(4) 6 Starting monochrome attribute INPUT CHAR(1)

7 Ending monochrome attribute INPUT CHAR(1) 8 Starting color attribute INPUT CHAR(1) 9 Ending color attribute INPUT CHAR(1) 10 Command buffer handle INPUT BINARY(4) 11 Low-level environment handle INPUT BINARY(4) 12 Error code I/O CHAR(*)

CRTDTAARA DTAARA(CANVAS) +

TYPE(*CHAR) LEN(1920) +

TEXT(AID bytes for WEA orders)

Figure 1: The QsnWrtDta API requires 12 parameters.

/******************************************************************************/
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 04:31

MC Press Online

/* PROGRAM - TESTWEA */ /* FUNCTION - test Write Extended Attributes (WEA) orders */ /* LANGUAGE - ILE CL */ /******************************************************************************/

PGM DCL &DATA *CHAR 64 DCL &X *DEC 5

CALLPRC 'QsnQry5250' (&DATA X'00000040' X'00000000') CHGVAR %SST(&DATA 52 1) X'00' CHGVAR &X %BIN(&DATA 52 2) IF (&X >= 128) (CHGVAR &X (&X - 128)) IF (&X >= 64) (CHGVAR &X (&X - 64)) IF (&X >= 32) (CHGVAR &X (&X - 32)) IF (&X >= 16) (CHGVAR &X (&X - 16)) IF (&X >= 8) (CHGVAR &X (&X - 8)) IF (&X < 4) DO SNDPGMMSG MSG('Extended attributes not supported.') MSGTYPE(*DIAG) RETURN ENDDO

/* clear the screen, set 24x80 mode */ CALLPRC 'QsnClrScr' ('3' *omit *omit *omit)

/* write to display, blink the cursor */ CALLPRC 'QsnWTD' (X'00' X'18' *omit *omit *omit)

/* write "COMPANY" at row 1, column 38 */ CALLPRC 'QsnWrtDta' ('COMPANY' X'00000007' *omit X'00000001' X'00000026'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "BLUE" at row 1, column 38 */ CALLPRC 'QsnWrtDta' (X'120382' X'00000003' *omit X'00000001' X'00000026'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "TURQUOISE" at row 1, column 39 */ CALLPRC 'QsnWrtDta' (X'120386' X'00000003' *omit X'00000001' X'00000027'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "GREEN" at row 1, column 40 */ CALLPRC 'QsnWrtDta' (X'120384' X'00000003' *omit X'00000001' X'00000028'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "YELLOW" at row 1, column 41 */ CALLPRC 'QsnWrtDta' (X'12038C' X'00000003' *omit X'00000001' X'00000029'*omit *omit *omit *omit *omit *omit *omit)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 04:31

MC Press Online

/* write extended color "RED" at row 1, column 42 */ CALLPRC 'QsnWrtDta' (X'120388' X'00000003' *omit X'00000001' X'0000002A'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "WHITE" at row 1, column 43 */ CALLPRC 'QsnWrtDta' (X'12038E' X'00000003' *omit X'00000001' X'0000002B'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "PINK" at row 1, column 44 */ CALLPRC 'QsnWrtDta' (X'12038A' X'00000003' *omit X'00000001' X'0000002C'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "RESUME BACKGROUND" at row 1, column 45 */ CALLPRC 'QsnWrtDta' (X'120380' X'00000003' *omit X'00000001' X'0000002D'*omit *omit *omit *omit *omit *omit *omit)

/* write "invoice" at row 3, column 38 */ CALLPRC 'QsnWrtDta' ('invoice' X'00000007' *omit X'00000003' X'00000026'*omit *omit *omit *omit *omit *omit *omit)

/* write extended attribute "UNDERLINE" at row 3, column 40 */ CALLPRC 'QsnWrtDta' (X'120184' X'00000003' *omit X'00000003' X'00000028'*omit *omit *omit *omit *omit *omit *omit)

/* write extended attribute "RESUME BACKGROUND" at row 3, column 41 */ CALLPRC 'QsnWrtDta' (X'120180' X'00000003' *omit X'00000003' X'00000029'*omit *omit *omit *omit *omit *omit *omit)

/* create 9-byte input field at row 5, column 37 */ CALLPRC 'QsnSetFld' (*omit X'00000009' X'00000005' X'00000025' X'4000'*omit *omit *omit *omit *omit *omit *omit)

/* write 2 extended attributes "RED" and "REVERSE" at row 5, column 37 */ CALLPRC 'QsnWrtDta' (X'120388120181'X'00000006' *omit X'00000005' X'00000025'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "WHITE" at row 5, column 40 */

CALLPRC 'QsnWrtDta' (X'12038E' X'00000003' *omit X'00000005' X'00000028'*omit *omit *omit *omit *omit *omit *omit)

/* write extended color "BLUE" at row 5, column 42 */ CALLPRC 'QsnWrtDta' (X'120382' X'00000003' *omit X'00000005' X'0000002A'*omit *omit *omit *omit *omit *omit *omit)

/* write 2 extended attributes "RESUME BACKGROUND" at row 5, column 46 */ CALLPRC 'QsnWrtDta' (X'120380120180'X'00000006' *omit X'00000005' X'0000002E'*omit *omit *omit *omit *omit *omit *omit)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 04:31

MC Press Online

/* wait for user to press a function key */ CALLPRC 'QsnGetAID' (&DATA *omit *omit) ENDPGM

Figure 2: The TESTWEA program generates WEA orders.

Figure 3: This screen capture of the TESTWEA progam shows abutting extended attributes and extended colors.

X'12 01 00' null - continue currently defined extended attribute X'12 01 80' end currently defined extended attribute and resume 5250 attribute X'12 01 81' reverse X'12 01 82' highlight X'12 01 83' highlight + reverse X'12 01 84' underline X'12 01 85' underline + reverse X'12 01 86' underline + highlight X'12 01 87' underline + highlight + reverse X'12 01 88' blink X'12 01 89' blink + reverse X'12 01 8A' blink + highlight X'12 01 8B' blink + highlight + reverse X'12 01 8C' blink + underline X'12 01 8D' blink + underline + reverse X'12 01 8E' blink + underline + highlight X'12 01 8F' blink + underline + highlight + reverse X'12 01 90' separator X'12 01 91' separator + reverse X'12 01 92' separator + highlight X'12 01 93' separator + highlight + reverse X'12 01 94' separator + underline X'12 01 95' separator + underline + reverse X'12 01 96' separator + underline + highlight X'12 01 97' separator + underline + highlight + reverse X'12 01 98' separator + blink X'12 01 99' separator + blink + reverse X'12 01 9A' separator + blink + highlight X'12 01 9B' separator + blink + highlight + reverse X'12 01 9C' separator + blink + underline X'12 01 9D' separator + blink + underline + reverse X'12 01 9E' separator + blink + underline + highlight X'12 01 9F' separator + blink + underline + highlight + reverse

Figure 4: Extended attributes you can create with WEA orders.

X'12 03 00' null - continue currently defined extended color X'12 03 80' end currently defined extended color and resume 5250 color X'12 03 81' same as X'80'
http://www.mcpressonline.com Powered by Joomla! Generated: 28 August, 2008, 04:31

MC Press Online

X'12 03 82' blue X'12 03 83' blue (different shade of blue than X'82' on some displays) X'12 03 84' green X'12 03 85' green (different shade of green than X'84' on some displays) X'12 03 86' turquoise X'12 03 87' turquoise (different shade of turquoise than X'86' on some displays) X'12 03 88' red X'12 03 89' red (different shade of red than X'88' on some displays) X'12 03 8A' pink X'12 03 8B' pink (different shade of pink than X'8A' on some displays) X'12 03 8C' yellow X'12 03 8D' yellow (different shade of yellow than X'8C' on some displays) X'12 03 8E' white X'12 03 8F' white (different shade of white than X'8E' on some displays)

Figure 5: Extended colors you can create with WEA orders.

X'20' green X'21' green + reverse X'22' white X'23' white + reverse X'24' green + underline X'25' green + underline + reverse X'26' white + underline X'27' nondisplay X'28' red X'29' red + reverse X'2A' red + blink X'2B' red + blink + reverse X'2C' red + underline X'2D' red + underline + reverse X'2E' red + blink + underline X'2F' nondisplay X'30' turquoise + separator X'31' turquoise + separator + reverse X'32' yellow + separator X'33' yellow + separator + reverse X'34' turquoise + underline X'35' turquoise + underline + reverse X'36' yellow + underline X'37' nondisplay X'38' pink X'39' pink + reverse X'3A' blue X'3B' blue + reverse X'3C' pink + underline X'3D' pink + underline + reverse X'3E' blue + underline X'3F' nondisplay

Figure 6: Single-byte 5250 display attributes create regular attributes and colors on all workstations.

F13 F14 F15 F16 F17 F18 F19

F1 F2 F3 F4 F5 F6 F7 F8 F12

Blue Green Turquoise Red Pink Yellow White Black

Figure 7: Photocopy this function key template and set it on your keyboard for the PAINT program.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 August, 2008, 04:31