GDDM services on OS/390

These services apply to native OS/390 batch, TSO, ISPF, and CICS

Native OS/390 batch and TSO

To use GDDM services for printing QMF objects, you must:

1. Choose a GDDM nickname for the print device, as explained in Choosing a GDDM nickname for your printer.

   Nicknames enable you to predefine complex print or display devices to simplify the work of your end users. Nicknames define device characteristics that indicate to GDDM how to format and distribute the report, and they can define both local and remote devices.

2. Update the GDDM defaults module, ADMADFT, with the specifications of your nickname.
3. Allocate the ddname ADMDEFS. Allocating the ddname ADMDEFS is explained in Allocating the nickname file for native OS/390 batch, TSO and ISPF.
4. Update the PRINTER field of the user's row in the Q.PROFILES table.

CICS

To use GDDM services for printing QMF objects, you must:

1. Choose a GDDM nickname for the print device.

   Nicknames enable you to predefine complex print or display devices to simplify the work of your end users. Nicknames define device characteristics that indicate to GDDM how to format and distribute the report, and they can define both local and remote devices.

2. Update the GDDM defaults module, ADMADFC, with the specifications of your nickname.
3. Update CICS resource definitions with the values in the nickname specification, so that CICS can link the nickname with the physical device it manages.
4. Update the PRINTER field of the user's row in the Q.PROFILES table.

Choosing a GDDM nickname for your printer

Here is information on the data sets GDDM searches for.

Native OS/390 batch, TSO, and ISPF

In native OS/390 batch and TSO, when a user enters a printer name on the PRINTER keyword of the QMF PRINT command, GDDM first searches the ADMDEFS data set and then the defaults module, ADMADTC, for a matching nickname that defines how and where to direct the output.

CICS

In CICS, GDDM searches only the defaults module, ADMADTC. GDDM uses nicknames to recognize all the devices with which it can communicate (including terminals).

Choosing the right type of GDDM device

The printer nickname you use depends on the type of device:

• Family 1 devices specify auxiliary devices attached to a workstation using GDDM-PCLK. A Family 1 device can also include display devices, such as 3270 data-stream terminals.
• Family 2 devices include devices such as IBM 3270 terminals and queued printers.
• Family 3 devices are system printers that support the ANSI code of carriage control characters.
• Family 4 devices are advanced function printers for which you need to use the ADMOPUT and ADMOPUJ utilities (in TSO, and native OS/390 batch only) to print output. These utilities are provided by GDDM.

This chapter explains how to define nicknames for Family 1, 2, and 3 devices. For more information on how to set up a nickname for a Family 4 printer and use the ADMOPUT and ADMOPUJ utilities, see the GDDM System Customization and Administration manual for GDDM or the appropriate GDDM Installation and System Management manual. These publications also provide more information on each type of GDDM device.

Creating the nickname specification

Here are the instructions to create nicknames on native OS/390, TSO, and CICS.

Native OS/390 batch, TSO, and ISPF

Add the nickname to your ddname ADMDEFS data set. GDDM looks at this data set first. If the nickname is not found, GDDM looks in the external default module, ADMADFT, in which you define a GDDM ADMMNICK specification.

CICS

To create a nickname in CICS, first define a GDDM ADMMNICK specification in the GDDM external default module ADMADFC. This specification indicates the device characteristics to GDDM, such as the number of lines per page the printer can handle, and how the printer is managed by CICS.

Use the format shown in Figure 111 for your ADMMNICK specification.

ADMMNICK NAME=nickname,TOFAM=family_type,
DEVTOK=device_token(,TONAME=name)

TONAME is used only in CICS.

• Use NAME to indicate a 1-character to 8-character printer nickname to use with the QMF PRINT command. For example, if MYPRTR is the nickname, users can enter the command: PRINT REPORT (PRINTER=MYPRTR. NAME can be a single name, a list of names separated by commas, or a name with a leading or trailing ? used as a wildcard to send output to multiple printers that have similar names.
• Use TOFAM to indicate the type of device you are using. GDDM recognizes four families of devices, and handles each differently.
• Use DEVTOK to indicate a valid GDDM device token, which uniquely identifies a device and its print configuration (for example, a 3820 printer that prints 60 rows by 85 columns, 6 lines per inch). For a list of valid device tokens, see the GDDM System Customization and Administration manual or the GDDM Installation and System Management for OS/390 manual for GDDM.
• In CICS, the TONAME field points to entries in the TCT or DCT so that CICS is able to properly manage communication between GDDM and the printer. Use TONAME to point to the name of a 1-character to 4-character printer definition name with a value that depends on the type of device:
  • If the nickname defines a Family 1 or 2 printer, TONAME points to a matching entry in the CICS terminal control table (TCT), which defines the printer to CICS. In the matching entry, the TRMIDNT field has the same value as TONAME.

    If you define the printer to CICS using CICS resource definition online (RDO) to update the CICS system definition (CSD) file, the TERMINAL attribute has the same value as TONAME.

  • If the nickname defines a Family 3 printer, TONAME points to a matching entry in the CICS destination control table (DCT), which defines the printer to CICS. In the matching entry, the DESTID field has the same value as TONAME.

A unique label can be added to the syntax. For example, GDDMPRT1 is a possible label for the nickname definition:

GDDMPRT1 ADMMNICK NAME=MYPRINT,TOFAM=3,DEVTOK=ADMKSYSP

Example nickname for a family 1 or 2 GDDM printer

To define the nickname GRAPHIC for a Family 1 or 2 GDDM printer, you might use an ADMMNICK specification similar to the one in Figure 112. This specification is for a Family 2 GDDM printer (use TOFAM=1 for a Family 1 GDDM printer). It uses the device token R87S, an example of a token for a remotely attached 3287 printer.

ADMMNICK NAME=GRAPHIC,TOFAM=2,DEVTOK=R87S,TONAME=GRAP

Native OS/390 batch, TSO and ISPF

After you create your nickname in TSO, and native OS/390 batch, a temporary data set is created as a result of running the QMF PRINT command and specifying a nickname that already exists. This data set is userid.ADMPRINT.REQUEST.#nnnnn, where nnnnn is a sequence number. You can then print the data set using the ADMOPUT utility. You can also use the ADMOPUJ utility to write your print job to the JES spool.

CICS

If you use either of the GDDM print utilities (ADMOPUT or ADMOPUJ) to print QMF objects using GDDM nicknames, the QMF-supplied GDDM map groups must be made available to the GDDM print utility. The ADMGGMAP DD statement contains the name of the data set (QMF720.DSQMAPE) that holds the map groups:

//ADMGGMAP DD DSN=QMF720.DSQMAPE,DISP=SHR

Without this statement, any attempt to print a form on a Family 2 printer ends in an error. For more information on the GDDM print utilities, see the GDDM Installation and System Management manual if you are using GDDM Version 2 Release 3 or the GDDM System Customization and Administration manual if you're using GDDM Version 3 Release 1.

Important: In CICS, after you create the ADMMNICK specification, link the name with a physical device by updating the TCT. Make sure TONAME in the ADMMNICK specification and TRMIDNT in the TCT have matching values.

You can also use CICS RDO facilities to update the CSD online. If you define the printer this way, make sure the TERMINAL attribute in the CSD and TONAME in the ADMMNICK specification have matching values.

Example nickname for a family 3 GDDM printer

Use this information to define the nickname for a family 3 GDDM printer on native OS/390 batch and TSO.

Native OS/390 batch, TSO and ISPF

To define the nickname 370PRINT for a Family 3 GDDM printer, you might use an ADMMNICK specification similar to the one in below.

ADMMNICK NAME=370PRINT,TOFAM=3,DEVTOK=R87S,TONAME=370P (CICS)

ADMMNICK NAME=370PRINT,TOFAM=3,DEVTOK=R87S (CMS)

After you create your nickname in TSO or native OS/390 batch , a ddname ADMLIST is created. You can then send the formatted file to the printer you have chosen.

CICS

To define the nickname 370PRINT for a Family 3 GDDM printer, you might use an ADMMNICK specification similar to the one in below.

ADMMNICK NAME=370PRINT,TOFAM=3,DEVTOK=R87S,TONAME=370P (CICS)

ADMMNICK NAME=370PRINT,TOFAM=3,DEVTOK=R87S (CMS)

After you create the ADMMNICK specification in CICS, link the name with a physical device by updating the DCT, as shown in the example in Figure 118. Make sure TONAME in the ADMMNICK specification and DESTID in the DCT have matching values.

Example nickname for a family 4 GDDM printer on native OS/390 batch, TSO or ISPF

To define the nickname 3900PRNT for a Family 4 GDDM printer, you might use an ADMMNICK specification similar to the one below.

ADMMNICK NAME=3900PRNT,TOFAM=4,DEVTOK=R87S

After you create your nickname, the ddname ADMIMAGE is created. You can spool the file to PSF/OS/390 automatically through JES if you have the CSPOOL processing option set. For more information about Family 4 printing, see theGDDM System Customization and Administration manual.

Defining multiple nicknames with one definition

You can use a single nickname to define multiple printer addresses by including the wildcard ? in your nickname definition, like this:

ADMMNICK TOFAM=3,NAME=MYPRINT?,PROCOPT=((PRINTCTL,0))

The nickname MYPRINT? allows you to route print output to printers named MYPRINT1, MYPRINT2, MYPRINTA, and so on. For example, when you enter:

PRINT REPORT (PRINTER=MYPRINT2

GDDM uses the nickname definition for the MYPRINT? nickname to create a data set and direct the output from the PRINT command to the data set with ddname MYPRINT2.

Examples of nickname definitions

This section shows examples of nicknames you might use for Family 1, 2, or 3 devices. For examples on defining nicknames for Family 4 devices, see the GDDM System Customization and Administration manual for GDDM or the GDDM Installation and System Management for OS/390 manual for GDDM.

• 3800, 3812, or 3820 printer, 6 lines per inch: Use the following definition to define the nickname GDDMPRT1 for a Family 3 printer:

  GDDMPRT1 ADMMNICK TOFAM=3,DEVTOK=S3800N6,NAME=MYPRINT1

• 3800, 3812, or 3820 printer, 8 lines per inch: Use the following definition to define the nickname GDDMPRT2 for a Family 3 printer:

  GDDMPRT2 ADMMNICK TOFAM=3,DEVTOK=S3800N8,NAME=MYPRINT2

• Non-3800 system printer, 132 columns, 8 lines per inch: Use the following definition to define the nickname GDDMPRT3 for a Family 3 printer:

  GDDMPRT3 ADMMNICK TOFAM=3,DEVTOK=S1403W8,NAME=MYPRINT3

• A remotely attached 3287 (suitable for printing charts): Use the following definition to define the nickname GDDMPRT4 for a Family 2 printer:

  GDDMPRT4 ADMMNICK TOFAM=2,DEVTOK=R87,NAME=MYPRINT4

• Any destination without print control options: Use the following definition to define the nickname GDDMPRT5 for a Family 3 printer:

  GDDMPRT5 ADMMNICK TOFAM=3,PROCOPT=((PRINTCLTL,)),NAME=MYPRINT5

  The PROCOPT parameter specifies processing options using a print control (PRINTCTL) keyword, which allows you to specify a number of print control options. For example, you can use PRINTCTL to specify a page heading to be printed, the number of copies to print, and the width of margins. The zero in this example suppresses page headings.
  Attention: If the print data set has RECFM=F, GDDM printing changes the DCB of the data set from RECFM=F to RECFM=V.

  For a list of print control options and how to use them, see the GDDM System Customization and Administration manual.

• A PC printer using GDDM-PCLK (for DOS users): Use the following definition to define the nickname PCPRINT for a Family 1 printer:

  GDDMPRT6 ADMMNICK TOFAM=1,FAM=0,NAME=PCPRINT,TONAME=*,ADMPCPRT

  where * indicates the user's current device or the default value.

  To print to a workstation printer connected to DOS, GDDM-PCLK must be installed on your workstation.

Updating the GDDM defaults module with the nickname

Use this information to update the GDDM defaults module on native OS/390 batch, TSO, and CICS.

Native OS/390 batch, TSO and ISPF

In TSO, and native OS/390 batch, the external defaults module is ADMADFT.

The default modules also contain default values for the GDDM product. The modules are stored as members of the SADMSAM data set.

To update the modules with your nickname specification:

1. Edit the source file to add the nickname.
2. Enter your ADMMNICK specification after the ADMMDFT statements in the module.
3. Reassemble and link-edit the changed default module.

For more information on the defaults modules, see the GDDM System Customization and Administration manual for GDDM or the GDDM Installation and System Management for OS/390 for GDDM manual.

CICS

In CICS, the ADMMNICK nickname specifications reside in the GDDM external defaults module ADMADFC, which is supplied with the GDDM product.

The default modules also contain default values for the GDDM product. The modules are stored as members of the SADMSAM data set.

To update the modules with your nickname specification:

1. Edit the source file to add the nickname.
2. Enter your ADMMNICK specification after the ADMMDFT statements in the module.
3. Reassemble and link-edit the changed default module.

For more information on the defaults modules, see the GDDM System Customization and Administration manual for GDDM or the GDDM Installation and System Management for OS/390 for GDDM manual.

Testing the nickname definitions in external default files for native OS/390 batch, TSO and ISPF

Test your nickname definitions by placing them in an external default file and printing with them until you are satisfied they are working correctly. Then you can assemble them into external default modules. .

GDDM uses external default modules more efficiently than a data set to find a given nickname.

The decision to use external default files or modules affects a user's JCL, because an external default file requires a DD statement, while an external default module must be a member of a STEPLIB library. Your GDDM administrator can advise you on the JCL changes.

Allocating the nickname file for native OS/390 batch, TSO and ISPF

For TSO, and native OS/390 batch, the ddname of the nickname data set is ADMDEFS. You should allocate it when you start your QMF session. To add the ddname ADMDEFS to the user's logon procedure:

//ADMDEFS DD DSN=LOCAL.GDDM.NICKNAME,DISP=SHR

Using nicknames in CICS

In CICS, the nicknames are incorporated into user default specifications and assembled into the external defaults module ADMADFC.

After you update the ADMADFC module, you need to update the CICS resource definitions so that CICS can link the nickname with a physical device it manages.

Linking a Family 2 nickname with a physical device

QMF supports the use of GDDM nicknames for reports and requires nicknames for printing QMF charts, forms, and prompted queries. If you have printers described to CICS using VTAM and TCT entries, you must describe the printer as queued (GDDM Family 2 device). When using a Family 2 device, your ADMMNICK specification for TONAME points to a CICS TCT entry, as opposed to a DCT entry for Family 3 devices.

For example, for this nickname specification:

ADMMNICK NAME=GRAPHIC,TOFAM=2,DEVTOK=R87S,TONAME=GRAP

you can update the CICS TCT using a macro similar to the example shown below.

GRAP     DFHTCT TYPE=TERMINAL,
               ACCMETH=VTAM,
               TRMIDNT=GRAP,
               TRMTYPE=SCSPRT,
                   . . .
                   . . .
                   . . .

In VSE, all Family 1 and 2 devices must be described to CICS as queued.

Linking a family 3 nickname with a physical device

To use Family 3 devices, set up a GDDM nickname table as shown below.

GDDMPRT  ADMMNICK TOFAM=3,   FAMILY (SYSTEM PRINTER)            X
            NAME=SYSPRT,     PRINTER NAME (NICKNAME)            X
            DEVTOK=S1403W6,  DEVICE TOKEN (1403)                X
            TONAME=SYSP      TONAME MUST MATCH CICS DCT ENTRY

TheGDDM Installation and System Management for OS/390 manual for GDDM and the GDDM System Customization and Administration manual for GDDM describe the process of incorporating the nicknames into the user default specifications and assembling the user default specifications into external defaults module ADMADFC.

The TONAME parameter must have a matching entry in the CICS DCT as shown in Figure 118.

* THE GDDM NICKNAME IS SYSPRT AND THE
* LONGEST RECORD THAT CAN BE PRINTED
* IS 256.
 
     DFHDCT TYPE=SDSCI,DSCNAME=ADMSYSP,                         X
           RECFORM=VARBLK,                                      X
           RECSIZE=260,BLKSIZE=6050,TYPEFLE=OUTPUT
                .
                .
*  ENTRY FOR GDDM NICKNAME SYSPRT
SYSP     DFHDCT TYPE=EXTRA,DESTID=SYSP,DSCNAME=ADMSYSP,RSL=1

You also need to add the ddname ADMSYSP to the CICS start-up JCL, as follows:

//ADMSYSP  DD SYSOUT=A

Add the TYPE=SDSCI entry shown in Figure 118 after all other TYPE=SDSCI entries in the DCT. The device address (SYS097) corresponds to the printer, 04E, according to the assign statement in the startup JCL. If you use SYSLST, CICS STATS is part of your QMF report. Instead, use an alternate printer.