Abstract

AFP-NEW PARAMETERS FOR TCP/IP IPDS PASSTHROUGH SNA

Pre/Co-Requisite PTF / Fix List

   REQ   LICENSED  PTF/FIX
   TYPE  PROGRAM   NUMBER   LICENSED PROGRAM DESCRIPTION
   ----  --------  -------  -----------------------------------------------
   PRE   5763999   MF09268  OPERATING SYSTEM/400
   CO    5763SS1   SF24167  OPERATING SYSTEM/400
   CO    5763SS1   SF24143  OPERATING SYSTEM/400
   CO    5763SS1   SF24142  OPERATING SYSTEM/400
   CO    5763SS1   SF24141  OPERATING SYSTEM/400
   CO    5763SS1   SF24140  OPERATING SYSTEM/400
   CO    5763SS1   SF24139  OPERATING SYSTEM/400
   CO    5763SS1   SF24138  OPERATING SYSTEM/400

APAR Error Description / Circumvention

DESCRIPTION OF PROBLEM FIXED FOR APAR SA44304 :
-----------------------------------------------
   Add configuration support for new functions provided by the
   IBM Print Services Facility for OS/400: TCP/IP support,
   sharing of a PSF Direct SNA session and IPDS passthrough.
 
 
CORRECTION FOR APAR SA44304 :
-----------------------------
   See the special instructions section of this cover letter for
   details.
 
CIRCUMVENTION FOR APAR SA44304 :
--------------------------------
 
   None.

Activation Instructions

   If this PTF is applied or removed as a "Delayed" PTF, which
   requires an IPL, no special consideration is necessary.  If this
   PTF is applied or removed "Immediate", you must first end all of
   the printer writers or end the QSPL subsystem.  The PTF will be
   effective when the writers are started up again.

Special Instructions

   Install this PTF if you use or are planning to use
   Print Services Facility/400 (PSF/400) and are installing PTFs
   for the following APARs:
 
     - SA44298. Provides support for printer attachments using
                TCP/IP.
     - SA44300. Adds support for IPDS passthrough
     - SA44303. Provides APPC enhancements permitting multiple
                AS/400s to share a PSF Direct session.
 
   The program provided in this PTF, QSYS/QPQXWAFP, provides an
   interface to a data area used by PSF/400 to obtain additional
   configuration information not provided through use of the
   CRTDEVPRT command. QPQXWAFP creates a data area in library QGPL
   with authority of *LIBCRTAUT.
 
   This cover letter assumes that you will use the command
   interface provided in this cover letter. This command interface
   is called WRKAFP2. Documentation provided here will reference
   the name WRKAFP2 and the parameters used by the command to
   provide an interface to QPQXWAFP. QPQXWAFP will be the program
   to process the command.
 
   This cover letter provides the following information:
 
     1. How to use WRKAFP2.
     2. Examples for using WRKAFP2.
     3. Data area migration concerns.
     4. Reference codes returned by QPQXWAFP.
     5. How to copy the source code for a suggested command
        interface, WRKAFP2, to QPQXWAFP from this cover letter
        into a physical file.
     6. How to compile the suggested command interface.
     7. Source code for a suggested command interface to QPQXWAFP.
 
   When configuring PSF/400 for any of these new functions, please
   refer to the cover letter for the PTF which adds that function,
   in addition to this cover letter.
 
   1. How to use WRKAFP2
   ---------------------
   WRKAFP2 has the following parameters:
 
     a. DEVD. Printer device name
        This is the name of the data area to be created, modified
        or migrated by WRKAFP2. The value may be any name
        permitted for a data area.
 
     b. PRINTONLY. Print data area only
        Use a value of *YES if you wish to print the contents of a
        data area previously created by WRKAFP2. Valid values are
        *YES and *NO. When *YES is specified, all other parameters
        are ignored. The default value is *NO.
 
     c. IPDSPASTHR. IPDS pass through
        Specifies if you are using PSF/400's IPDS Passthrough
        function. You may use this function when printing on any
        connection: Twinaxial, APPC and TCP/IP. Valid values are
        *YES and *NO. The default value is *NO.
 
     d. TCPIP. TCP/IP.
        Specifies if you are attaching to a device which requires
        PSF/400's TCP/IP support. Valid values are *YES and *NO. If
        you specify *YES, you will have to specify values for
        RMTSYS and PORT; see below. The default value is *NO.
 
     e. RMTSYS. Remote system.
        Specifies the remote system name of the printer. You may
        use either a host name or an IP address.
 
     f. PORT. Port.
        Specifies the port number for the device. Valid values
        range from 1-65535.
 
     g. ACTTMR. Activation timer.
        Specifies the number of seconds PSF/400 will wait for a
        printer to respond to an activation request. If the printer
        does not respond within this time, PSF/400 terminates. The
        value specified depends on what is required in your
        environment. The value you select is dependent on whether
        you are sharing the printer with another PSF, or the length
        of time required for an activation request to reach the
        printer. This parameter is used only for TCP/IP-attached
        printers. Acceptable values are 1-2550 seconds and *NOMAX
        (wait forever). The default value is 170.
 
     h. RETRY. SNA retry count
        Specifies the number of retries PSF/400 should attempt when
        trying to establish a session with a device. RETRY may be
        used for devices attached by APPC. This value is ignored
        for Twinax and TCP/IP. This parameter is designed for use
        with PSF Direct. If you are sharing a PSF Direct-attached
        printer with another PSF, then you may want to give
        consideration to how this value should be set. Valid values
        are 1-99 and *NOMAX (try forever). The default value is 2.
 
     i. RETRYDLY. Delay time between SNA retries.
        Specifies the number of seconds to wait between retry
        attempts to establish a session. This parameter
        applies to APPC-configured printers only. This parameter
        only applies if the RETRY parameter has a value greater
        than 0. This parameter is designed for use with PSF Direct.
        If you are sharing a PSF Direct-attached printer with
        another PSF, then you may want to give consideration to how
        this value should be set. Valid values are 0 -999 seconds.
        The default value is 0.
 
     j. INACTTMR. Inactivity timer.
        Specifies the length of time PSF/400 will maintain a
        session with the printer while there are no spooled files
        with a status of RDY. If the specified time elapses,
        PSF/400 closes the connection with the printer, which
        permits another PSF to use the printer. This parameter is
        used for APPC- and TCP/IP-attached printers only. Valid
        values are 1-30 minutes, *NOMAX (never close the
        connection), *SEC15 (15 seconds) and *SEC30 (30 seconds).
        The default value is *NOMAX.
 
     The remaining four parameters have already been made available
     by setting values in a data area accessed by PSF/400. They are
     made available through WRKAFP2.
 
     k. SBP. Suppress blank pages.
        Specifies that PSF/400 does not issue a blank page after
        every separator page and spool file copy that contains an
        odd number of pages. This parameter is used for the 3835
        and 3900 printers only. Valid values are *YES and *NO. The
        default value is *NO.
 
     l. PSC. Page size control.
        Specifies whether PSF/400 sets the page size (forms) in
        the printer. This parameter only applies to the 4224, 4230,
        4234, 4028, 6404, 6408, and 6412 printers. Valid values are
        *YES and *NO. If *YES is specified, the page size in the
        spooled file overrides the printer's configuration. The
        default value is *NO.
 
     m. DRF. Disable resident fonts.
        Specifies whether PSF/400 does not support the resident
        fonts on a printer that has resident fonts. If *YES is
        specified, PSF/400 will map resident font references to the
        equivalent host font and then download the host font to the
        printer. Valid values are *YES and *NO. The default value
        is *NO.
 
     n. DRR. Disable resource retention.
        Specifies if PSF/400 should delete page segments and
        overlays from the printer after printing a spooled file
        which references page segments and overlays. Valid values
        are *YES and *NO. The default value is *NO.
 
   2. Examples for using WRKAFP2
   -----------------------------
 
   This section gives examples of how to use WRKAFP2 for
   different printing requirements. The term printer is used to
   mean either an IBM IPDS printer which provides TCP/IP support
   or the i-data 7913 Printer LAN Attachment.
 
     a. Using WRKAFP2 to configure PSF/400 to use IPDS Passthrough
        for a Twinaxial-attached printer.
 
        WRKAFP2 DEVD(PRT3112) IPDSPASTHR(*YES)
 
        Changes to the printer device description are not required.
        Note that IPDSPASTHR(*YES) may be specified when printing
        on any connection: Twinaxial, APPC and TCP/IP.
 
     b. Using WRKAFP2 to configure PSF/400 to attach to a printer
        which provides TCP/IP support.
 
        WRKAFP2 DEVD(PRT3130) TCPIP(*YES) RMTSYS('9.5.12.102')
                PORT(5001)
 
        See the PTF cover letter for APAR SA44298 for additional
        configuration information.
 
     c. Using WRKAFP2 to configure PSF/400 on two or more AS/400s
        to continually share a TCP/IP-attached printer. The
        following must be done on each AS/400:
 
        WRKAFP2 DEVD(PRT3130) TCPIP(*YES) RMTSYS('9.99.12.112')
                PORT(5001) ACTTMR(*NOMAX) INACTTMR(5)
 
        This definition configures PSF/400 to wait forever
        ACTTMR(*NOMAX) to establish a connection with a printer.
        After making a connection, if there are no spooled files
        with a status of RDY on the output queue in use by PSF/400
        after 5 minutes, INACTTMR(5), then the connection with the
        printer is ended. PSF/400, however, will not end. As soon
        as a spooled file becomes RDY, PSF/400 will attempt to make
        a connection with the printer. The value specified for
        ACTTMR affect the length of time for which PSF/400 attempts
        to again make a connection with the printer.
 
        Note that while one AS/400 is printing, one or more AS/400s
        may be attempting to make a connection. As soon as an
        AS/400 ends the connection to a printer, another AS/400 can
        get a connection to the printer.
 
        See the PTF cover letter for APAR SA44298 for additional
        configuration information.
 
     d. Using WRKAFP2 to configure PSF/400 on two or more AS/400s
        to continually share a printer attached through the PSF
        Direct function provided by PSF/2 and PSF/6000.
 
        WRKAFP2 DEVD(PSFD3900) RETRY(*NOMAX) RETRYDLY(60)
                INACTTMR(*SEC30)
 
        This definition configures PSF/400 to make an infinite
        number of attempts, RETRY(*NOMAX), to establish a
        connection with PSF/2 or PSF/6000. PSF/400 will pause
        60 seconds, RETRYDLY(60), between each attempt to
        establish a connection. After making a connection, if
        there are no spooled files with a status of RDY on the
        output queue in use by PSF/400 after 30 seconds,
        INACTTMR(*SEC30), then the connection with the printer is
        ended. However, PSF/400 will not end. As soon as a spooled
        file becomes RDY, PSF/400 will attempt to make a connection
        with the printer. The values specified for RETRY and
        RETRYDLY affect the length of time for which PSF/400
        attempts to again make a connection with the printer.
 
        Note that while one AS/400 is printing, one or more AS/400s
        may be attempting to make a connection. As soon as an
        AS/400 ends the connection to a printer, another AS/400 can
        get a connection to the printer.
 
        Changes to the printer device description are not required.
 
   3. Data area migration concerns
   -------------------------------
 
   You may already be using a data area to control some aspects of
   AFP printing. WRKAFP2 will automatically migrate that data area
   to the new one required to configure for the above-mentioned new
   functions. This is necessary if the existing data area is not of
   the correct size.
 
   A data area will be migrated if the following conditions exist:
 
     a. The data area specified for DEVD in WRKAFP2 exists in
        library QGPL.
     b. The first eight bytes of the data area are set to WWPDTRHR.
 
   The migration performed by WRKAFP2 involves the following steps:
     a. Save the value stored within the existing data area.
     b. Delete the existing data area.
     c. Create a new data area of the correct size.
     d. Copy the values from the old data area to the new data
        area.
     e. Add any new values you have specified to the new data area.
 
   4. Reference Codes returned by QPQXWAFP.
   ----------------------------------------
   Listed below are the reference codes that can be returned by
   QPQXWAFP. An explanation for each code is given.
 
   Reference code   Explanation
   --------------   -----------
   QPQXWAFP 0001    You gave a blank value for DEVD. Use WRKAFP2
                    again and specify a nonblank value for DEVD.
   QPQXWAFP 0002    You specified TCPIP(*YES) but did not give a
                    value for RMTSYS. Use WRKAFP2 again and specify
                    a value for RMTSYS.
   QPQXWAFP 0003    You specified TCPIP(*YES) but did not give a
                    value for PORT. Use WRKAFP2 again and specify a
                    value for PORT.
   QPQXWAFP 0004    You specified PRINTONLY(*YES) but the specified
                    data area could not be found. Use WRKAFP2
                    again, specifying a data area created by
                    QPQXWAFP.
   QPQXWAFP 0005    QPQXWAFP was unable to open a spooled file for
                    output. Review the messages in your job log for
                    additional information.
   QPQXWAFP 0006    QPQXWAFP was unable to write to the spooled
                    file it had opened. Review the messages in your
                    job log for additional information.
   QPQXWAFP 0007    QPQXWAFP was unable to close the spooled file
                    it was using. Review the messages in your job
                    log for additional information.
   QPQXWAFP 0009    You specified PRINTONLY(*YES) but the specified
                    data area could not be interpreted by QPQXWAFP.
                    This means that the data area was not created
                    by QPQXWAFP. Delete the data area, DLTDTAARA,
                    and then use QPQXWAFP to create the data area.
   QPQXWAFP 0009    The data area to be migrated does not have the
                    first eight bytes set to WWPDTRHR. Delete the
                    data area, DLTDTAARA, and then run WRKAFP2.
   QPQXWAFP 0010    The caller of QPQXWAFP does not have authority
                    to the data area specified for DEVD.
   QPQXWAFP 9999    An existing data area was successfully migrated
                    to a new data area.
 
   If a data area is successfully created or changed (but not
   migrated), a reference code is not issued by QPQXWAFP.
 
   5. How to copy the source code for a suggested command
      interface to QPQXWAFP into a physical file.
   ---------------------------------------------------------------
   These instructions assume you have a source physical file
   named QCLSRC.
 
     a)  WRKMBRPDM QGPL/QCMDSRC
 
     b)  Press F6 to create a new member.  Name it WRKAFP2 and
         the type is CMD. Give it a meaningful description. Press
         Enter.
 
     c)  You now have the SEU edit screen.  Press F15 to
         Browse/Copy member.
 
     d)  Select:
              Selection:         1 = Member
              Copy all records:  N
              Member:            QSF24144
              File:              QAPZCOVER
              Library:           QGPL
        Press Enter.  This should give you a split screen.
 
     e)  At the command line for the screen type F WRKAFP2: CMD and
         press Enter. After the character string is located, press
         F16 two times. You will see a line that begins
         "WRKAFP2: CMD". Type a CC in the control space at the
         beginning of the line.
 
     f)  Now go to the end of the program. Type B at the command
         line to go to the end of the member. Type a CC in that
         line.
 
     g)  Move the cursor back to the new member you are creating
         and type an "A" at the first line.  Press Enter.
 
     h)  Press F12 to end the split screen.  F3 to end the edit
         session and Enter to save the new source.
 
     i)  You must now compile the command. Use the following to
         compile your command:
 
         CRTCMD CMD(QGPL/WRKAFP2) PGM(QSYS/QPQXWAFP)
                SRCFILE(QGPL/QCMDSRC)
 
     After the command successfully compiles, you are ready to use
     the WRKAFP2 command. In order that the values specified by the
     use of WRKAFP2 take effect, you must perform the following:
 
       1. End PSF/400 (ENDWTR), if it is active.
       2. Use WRKAFP2 to set the values.
       3. Start PSF/400 (STRPRTWTR).
 
     Values specified with WRKAFP2 take effect only when PSF/400
     is started (STRPRTWTR).
 
   6. How to compile the suggested command interface.
 
      CRTCMD CMD(QGPL/WRKAFP2) PGM(QSYS/QPQXWAFP)
             SRCFILE(my_lib/QCMDSRC)
 
   7. Source code for a suggested command interface to QPQXWAFP
   ------------------------------------------------------------
 
    WRKAFP2: CMD    PROMPT('Work with AFP 2.0')
            PARM  KWD(DEVD) TYPE(*NAME) LEN(10) RSTD(*NO) +
                       MIN(1) MAX(1) DTAARA(*YES) EXPR(*YES) +
                       VARY(*NO) PASSATR(*NO) PROMPT('Printer +
                       device name')
            PARM  KWD(PRINTONLY) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)  +
                       SPCVAL((*YES Y) (*NO N)) +
                       PROMPT('Print data area only')
            PARM  KWD(IPDSPASTHR) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)  +
                       SPCVAL((*YES Y) (*NO N)) +
                       PROMPT('IPDS pass through')
            PARM  KWD(TCPIP) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)  +
                       SPCVAL((*YES Y) (*NO N)) +
                       PROMPT('TCP/IP support')
            PARM  KWD(RMTSYS) +
                       TYPE(*CHAR) LEN(255) MIN(0) MAX(1) +
                       PMTCTL(TCPIP) +
                       PROMPT('Remote system')
            PARM  KWD(PORT) +
                       TYPE(*INT4) RSTD(*NO) +
                       RANGE(1 65535) MIN(0) MAX(1) +
                       FULL(*NO) EXPR(*YES) +
                       PASSATR(*NO) +
                       PMTCTL(TCPIP) +
                       PROMPT('Port')
            PARM   KWD(ACTTMR) +
                       TYPE(*INT4) +
                       RANGE(1 2550)  SPCVAL((*NOMAX 0)) +
                       MIN(0) MAX(1)         +
                       DFT(170)     +
                       PMTCTL(TCPIP) +
                       PROMPT('Activation timer')
            PARM  KWD(RETRY) +
                       TYPE(*INT2) RSTD(*NO) DFT(2)  +
                       RANGE(1 99) MIN(0) MAX(1) +
                       SPCVAL((*NOMAX X'FFFF')) +
                       FULL(*NO) EXPR(*YES) +
                       PASSATR(*NO) +
                       PMTCTL(TCPIPNO) +
                       PROMPT('APPC retry count')
            PARM  KWD(RETRYDLY) +
                       TYPE(*INT2) RSTD(*NO) DFT(0)  +
                       RANGE(0 999) MIN(0) MAX(1) +
                       FULL(*NO) EXPR(*YES) +
                       PASSATR(*NO) +
                       PMTCTL(TCPIPNO) +
                       PROMPT('Delay between APPC retries')
            PARM   KWD(INACTTMR) +
                       TYPE(*INT4) +
                       RANGE(1 30) +
                       MIN(0) MAX(1)            +
                       DFT(*NOMAX) +
                       SPCVAL((*NOMAX 0) (*SEC15 254) +
                              (*SEC30 255)) +
                       PROMPT('Inactivity timer')
            PARM  KWD(SBP) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)     +
                       SPCVAL((*YES Y) (*NO N)) +
                       PMTCTL(*PMTRQS) +
                       PROMPT('Suppress blank pages')
            PARM  KWD(PSC) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO) +
                       SPCVAL((*YES Y) (*NO N)) +
                       PMTCTL(*PMTRQS) +
                       PROMPT('Page size control')
            PARM  KWD(DRF) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)  +
                       SPCVAL((*YES Y) (*NO N)) +
                       PMTCTL(*PMTRQS) +
                       PROMPT('Disable resident fonts')
            PARM  KWD(DRR) +
                       TYPE(*CHAR) LEN(1) MIN(0) MAX(1) +
                       FILE(*NO) RSTD(*YES) DFT(*NO)  +
                       SPCVAL((*YES Y) (*NO N)) +
                       PMTCTL(*PMTRQS) +
                       PROMPT('Disable resource retention')
   TCPIP:   PMTCTL     CTL(TCPIP) COND((*EQ Y))
   TCPIPNO: PMTCTL     CTL(TCPIP) COND((*EQ N))
            PMTCTL     CTL(PRINTONLY) COND((*EQ N)) LGLREL(*AND)

Default Instructions

   THIS PTF CAN BE APPLIED IMMEDIATE OR DELAYED.

Supersedes

PTF/FIX NO(S).  APAR TITLE LINE
--------------  -----------------------------------------------------------
     NONE

Summary Information

System................. AS/400
Models................. *ALL
Release................ V3R1M0
Recompile.............. N
Library................ QSYS
MRI Feature............ NONE