RSCS 3.2.0 TCP/IP Enhancements

Product Number: 5684-096 Release 3.2.0

Table of Contents

TCP/IP Enhancements

  • RSCS 3.2.0 APARs Providing TCP/IP Enhancements
  • Domain Name Server Support
  • GETHOSTC MODULE
  • RSCS LOADLIB Enhancements
  • User Supplied Keywords
  • System Supplied Keywords
  • New Link Parameters
  • New Exit Parameters
  • Enhanced Exit Parameters
  • Exit Configuration Files
  • LPDXMANY Configuration file
  • LPRXONE and ASCXONE Configuration file
  • LPRXPSE and ASCXPSE Configuration file
  • LPR-type Link Exit Parameter List
  • New and Changed Messages
  • The PPS Command
  • The PPS XEDIT Macro
  • Configuring an RSCS TN3270E Printer Link
  • LINKDEFINE and DEFINE Statements for a TN3270E-Type Link
  • PARM Statement for a TN3270E-Type Link
  • Tag Options for a TN3270E-Type Link
  • UFT Support
  • UFT-type Link Driver
  • UFTD-type Link Driver
  • Managing UFT Links
  • Parm Statement for a UFT-Type Link
  • Parm Statement for a UFTD-Type Link
  • Start Command Parameters for a UFT-Type Link
  • Start Command Parameters for a UFTD-Type Link
  • UFTXOUT Routine
  • UFTXIN Routine
  • Examples of Username

  • TCP/IP Enhancements

    The following enhancements have been made to the TCP/IP capabilities of RSCS 3.2.0:

    • Addition of an Initial Time Out (ITO) PARM for LPR-type links.
    • Ability to override the default orientation, font name, font size, and additional leading size used by the LPR- and TCPASCII-type sample postscript exits when printing plain text files.
    • Ability to override the default filter used in the control file sent to a remote daemon by the LPR-type link sample exits.
    • Ability for the LPR- LPD- and TCPASCII-type link sample exits to read an external translation table
    • Ability for the LPR- and TCPASCII-type link sample postscript exits to read an external postscript program used when printing plain text files.
    • Ability for the LPR- and TCPASCII-type link sample postscript exits to read additional font names used when printing plain text files.
    • Ability for the LPD-type link sample exit to read an external configuration file to provide overrides to defaults used by the exit on a printer queue name basis when receiving a file from a remote host. Defaults which can be overridden include:
      • Logical record length up to 1280 characters
      • Number of lines per page
      • Spool file class
      • Spool file form name
      • Job name
      • PSF destination
      • Whether or not to paginate regardless of control file setting
      • Whether or not to translate the data received
      • User ID file should be spooled to
      • Node ID file should be spooled to
      • TCPXLBIN translate table to use
    • Ability to customize the control file created by the LPR-type link sample exits via parameters which can be defined in the sample exits configuration file.
    • Domain Name Server support for LPR-, TCPNJE-, TCPASCII-, and UFT-ype links.
    • A TN3270E-Type link intended for use with TELNET printer sessions.
    • Ability to override the host name portion of the control and data file names a LPR-type link constructs when sending the 'Receive control file' and 'Receive data file' subcommands to a remote daemon.
    • Ability for the LPR- and TCPASCII-type link sample non-postscript printer exits to handle simple PCL strings and SCS transparency orders imbedded anywhere within each record of the file being processed for printing.
    • Ability for the LPR- and TCPASCII-type link sample exits to split the prefix string before and after the separator page.
    • Ability for the LPR- and TCPASCII-type link sample exits to produce a two-page separator useful when duplexing.
    • Ability for users to provide keywords at the beginning of a file to contain overrides for a LPR-type link. Defaults which can be overridden include:
      • The fully-qualified host name
      • The dotted decimal host address
      • The one-character filter
      • The printer queue name
      • A prefix string
      • A suffix string
      • A translate table
      • The separator page setting

      The PPS EXEC and PPS XEDIT macro have been enhanced to support reading these keywords from an RSCS NAMES file. The command and macro syntax are provided later in this appendix.

    • Ability for an RSCS administrator to build form block tables to provide keywords which contain overrides for a LPR-type link. Defaults which can be overridden include:
      • The fully-qualified host name
      • The dotted decimal host address
      • The one-character filter
      • The printer queue name
      • A prefix string
      • A suffix string
      • A translate table
      • The form name
      • The separator page setting

      The spool file form name is used to select a form block table to provide the overrides used by the LPR-type link when printing. The form block table is built using a new exit routine, called LPRXFORM, which utilizes exit points 0 and 1.

    • Ability to have a LPR-type link place a file on hold when it has been unable to connect to a remote daemon. This capability can be used in conjunction with the RSCS events file to periodically take the file off hold and try connecting again.
    • Ability to limit the size of files, based on number of records, printed by a LPR-type link.
    • Support for the European currency character.
    • Ability to define the number of days a LPR-type link will place an undeliverable file on hold before requeueing it to a notify link.
    • Ability to define a timeout value for a LPR-type link which will cause the link to abort transmission, and place the file on hold, if a response is not received from the remote host.
    • Ability to select the local port range a LPR-type link will use.
    • Ability to supply TAG information when using the PPS EXEC and PPS XEDIT macro.
    • Unsolicited File Transfer (UFT) Support.
    • Support for POSIX translate tables in the LPR-type link sample exits.
    • Support for a separate translate table used for translating the control file in the LPR- and LPD-type link sample exits.
    • Support in the PPS EXEC and XEDIT macro for specifying a job name.
    • Support in the ASCXPSE and LPRXPSE exit configuration file for specifying an encoding vector to be included with the postscript program sent when printing plain text.
    • Support in the LPDXMANY configuration file to create PUNCH files instead of print files, and to specify the origin node name assigned so spool files the LPD link creates.
    • Ability for the LPRXPSE and ASCXPSE sample exits to split the suffix string before and after the trailer page.

    RSCS 3.2.0 APARs Providing TCP/IP Enhancements

    • APAR VM59999 provides:
    • APAR VM60615 provides:
      • A FOrm= exit parameter for the LPRXPSE and ASCXPSE sample exit routines.
      • A FILter= exit parameter for the LPRXONE, and LPRXPSE, sample exit routines.
      For further details, see "New Exit Parameters".
    • APAR VM60695 provides:
      • A configuration file for the LPDXMANY sample exit routine allowing an RSCS administrator to provide logical record length, lines per page, spool file class and form, job name, PSF destination, pagination, translation, and destination user ID for files received based on printer queue names, overriding the defaults used by the exit. For further details, see "LPDXMANY Configuration file".
    • APAR VM60931 provides:
    • APAR VM61295 provides:
    • APAR VM61374 provides:
      • A TN3270E-Type link which supports 3270 printer sessions created by TCP/IP. For further details, see "Configuring an RSCS TN3270E Printer Link",
      • Ability for the LPD-, LPR-, and TCPASCII-type link sample exits to read and use external translation tables. For further details, see "LPDXMANY Configuration file", "LPRXONE and ASCXONE Configuration file", and "LPRXPSE and ASCXPSE Configuration file".
      • Ability for the LPR-, and TCPASCII-type link sample postscript exits to read and use an external postscript program for printing plain text files. For further details, see "LPRXPSE and ASCXPSE Configuration file".
      • Ability for the LPR-, and TCPASCII-type link sample postscript exits to read and use additional font names for printing plain text files. For further details, see "LPRXPSE and ASCXPSE Configuration file".
      • Ability for the LPR-, and TCPASCII-type link LPRXONE and ASCXONE sample exits to handle simple protocol conversion which used to be handled by hardware. For further details, see "LPRXONE and ASCXONE Configuration file".
      • Ability for a LPR-type link to place a file on hold when it has been unable to connect to the remote daemon. The RSCS events file along with a FILehold= link parameter allows the link to periodically retry sending the file to a remote daemon. For further details, see "New Link Parameters".
      • A new sample exit, LPRXFORM, used in conjunction with a LPR-type link to provide overrides for link parameters based on the spool file form. Exit points 0 and 1 are used by LPRXFORM along with a SYStem= link parameter to allow the exits to be used by the link. For further details, see "System Supplied Keywords" and, "New Link Parameters".
      • Ability for a user to provide keywords at the beginning of a print file to provide overrides for LPR-type link parameters. The PPS EXEC and PPS XEDIT macro have been enhanced to read an RSCS NAMES file along with a USer= link parameter to allow users to provide keywords. For further details, see "User Supplied Keywords", "New Link Parameters", "The PPS Command" and, "The PPS XEDIT Macro".

        The PPS EXEC provided on the install ID's 406 disk is documented in "The PPS Command". The PPS XEDIT macro provided on the install ID's 406 disk is documented in "The PPS XEDIT Macro".

      • The LPDXMANY sample exit and configuration file have been enhanced with the following:
        • Support logical record lengths up to 1280 characters
        • Specify whether or not to do ASCII to EBCDIC translation through a parameter on the queuename record
        • Support setting the destination user ID through a parameter on the queuename record, instead of basing the destination user ID from the printer queue name
        • Pick a printer device type based on the maximum record length
        • Set the destination user ID to SYSTEM when a PSF destination is used
        For further details, see "LPDXMANY Configuration file".
    • APAR VM61635
    • APAR VM61791
      • The LPDXMANY sample exit and configuration file have been enhanced with the following:
        • Support setting the destination node ID through a parameter on the queuename record, instead of basing the destination node ID from the printer queue name
        • Pick a TCPXLBIN translate table, provided with VM/TCPIP, to use when translating the data and control file, through a parameter on the queuename record.
        For further details, see "LPDXMANY Configuration file".
      • A DAYshold= parameter for the LPR-type link. For further details, see "New Link Parameters"
      • A TImeout= parameter for the LPR-type link. For further details, see "New Link Parameters"
      • A SECure= parameter for the LPR-type link. For further details, see "New Link Parameters"
      • Addition of a TCPXlbin parameter on the PPS EXEC and XEDIT macro. For further details, see "The PPS Command", and "The PPS XEDIT Macro".
      • Ability to customize the control file created by the LPR-type link sample exits via the addition of DOMAINAME=, HOSTNAME=, and USERNAME= parameters within the exit configuration file. For further details, see "LPRXONE and ASCXONE Configuration file", and "LPRXPSE and ASCXPSE Configuration file".
    • APAR VM61891
    • APAR VM62148
      • Provides UFT support for &PGMNAME.. For further details, see "UFT Support".
      • Support for POSIX translate tables in the LPR-type link sample exits.
      • Support for a separate translate table used for translating the control file in the LPR- and LPD-type link sample exits.
    • APAR VM62240
      Provides support in the PPS EXEC and XEDIT macro for specifying a job name. For further details, see "The PPS Command", and "The PPS XEDIT Macro".
    • APAR's VM62369 and VM62504
      Provides additional PCL string support within the LPRXONE and ASCXONE sample exits, including:
      • The ability to override the header string
      • The ability to specify multiple PCL strings in each record.
      For further details, see "LPRXONE and ASCXONE Configuration file".
    • APAR VM62514
      Provides support in the LPRXPSE and ASCXPSE exit configuration file for specifying an encoding vector to be included with the postscript program sent when printing plain text. For further details, see "LPRXPSE and ASCXPSE Configuration file".
    • APAR VM62633
      Provides the ability for the LPRXPSE and ASCXPSE sample exits to split the suffix string before and after a trailer page. For further details, see "LPRXPSE and ASCXPSE Configuration file".
    • APAR VM62690
      Provides support in the LPDXMANY exit configuration file for creating PUNCH files instead of PRINT files, and for specifying the origin node assigned to spool files the LPD link creates. For further details, see "LPDXMANY Configuration file".

    Domain Name Server Support

    Domain Name Server support in RSCS is provided through enhancements made to the RSCS LPR-, TCPNJE-, TCPASCII, and UFT-type links and a new GETHOSTC MODULE.

    Note!
    On VM/ESA 2.3.0, 2.4.0, or z/VM, the RSCSDNS user ID is defined as the virtual machine supporting the RSCS domain name server function.

    Domain Name Server support in RSCS allows for the ability to supply a fully qualified host name, such as gdlvm7.endicott.ibm.com, when configuring LPR-, TCPNJE-, TCPASCII-, and UFT-type links. This support is an interface between the RSCS machine, and the DNS support defined in your VM TCP/IP configuration allowing RSCS to resolve a host name into a dotted decimal address.

    GETHOSTC MODULE

    GETHOSTC MODULE and GETHOSTC TEXT files are installed to the P684096K's 402 minidisk, or the VMSYS:P684096K.RSCS.XCHTEST SFS directory. This is a C MODULE which runs in it's own CMS virtual machine and does the Domain Name Server searches on behalf of RSCS. It will listen on a TCP/IP port for a connect request from an RSCS virtual machine. When a connect request is received, it will read a host name (up to 255-characters) sent by RSCS, issue the DNS search, and return the 4-byte IP address back to RSCS.

    The CMS virtual machine must be set up as follows before invoking the GETHOSTC module:

    • The runtime library for this compiler release must be linked and accessed. If on VM/ESA Version 1 you will need the runtime library from LE 1.5 or higher. If on VM/ESA Version 2 or z/VM Version 3 you can use the runtime library supplied with VM.
    • Issue
      GLOBAL LOADLIB SCEERUN
      
      SCEERUN is part of the C runtime library supplied with LE 1.5 or greater.
    • Link and access the TCPMAINT 592, or equivalent, minidisk.
    • Link and access the P684096K 402 (test Build disk) or P684096K 403 (production Build disk), or equivalent, minidisk, or the VMSYS:P684096K.RSCS.XCHTEST SFS directory.

    To start the module issue:

    GETHOSTC port
    
    where port is the TCP/IP port the module will listen on for connect requests; the default is 900.

    Multiple virtual machines can run the GETHOSTC MODULE all listening on the same port. Each of the user IDs running GETHOSTC will need to be added to the PORT statement in the PROFILE TCPIP configuration file (for the TCPIP virtual machine).

    The module will periodically check for command input. Two commands are supported:

    Query
    will return a message indicating the current RSU level
    SHUTDOWN
    terminates processing

    GETHOSTC TEXT file is provided to allow for the GETHOSTC MODULE to be rebuilt. To rebuild the module proceed with the following steps:

    • Global the following TXTLIB's:
      COMMTXT VMMTLIB SCEELKED SCEESPC SCEESPCO DMSCMT DMSCENV
      
      • COMMTXT is part of TCP/IP.

      • VMMTLIB, DMSCMT, and DMSCENV are part of VM/ESA and z/VM.

      • SCEELKED, SCEESPC, and SCEESPCO are part of the C runtime library supplied with LE 1.5 or greater.

    • Global the following LOADLIB:
      SCEERUN
      
      SCEERUN is part of the C runtime library supplied with LE 1.5 or greater.
    • Build the GETHOSTC module by issuing:
      CMOD GETHOSTC
      

      The CMOD EXEC is part of the C runtime library supplied with LE 1.5 or greater.

    • Follow local modification procedures to register the GETHOSTC MODULE as a full part replacement local modification.

    RSCS LOADLIB Enhancements

    Contains enhancements to the LPR-, TCPNJE-, TCPASCII-, and UFT-type links with support for 2 new link parameters:

    • HOSTName= to supply up to a 200-character host name. For further details, see "New Link Parameters".
    • DNSport= to supply the TCP/IP port which the GETHOSTC module is listening on, default is 900. For further details, see "New Link Parameters".

    Each link will issue a Domain Name search only if a HOST= link parameter (to supply an IP address) has not been specified and a HOSTName= link parameter has been supplied.


    User Supplied Keywords

    LPR-type links have the ability to search for keywords at the beginning of the spool file to determine how to handle and process the file, overriding parameters that may have been defined for the LPR link. An RSCS administrator can authorize users to provide keywords for use by LPR-type links using the USer=Yes link parameter (see "New Link Parameters"). These keywords are automatically inserted at the beginning of a file by the PPS EXEC and the PPS XEDIT MACRO. For more information, see "The PPS Command" and see "The PPS XEDIT Macro". In addition, the TCP/IP LPR EXEC provided with TCP/IP Function Level 310 or higher can be used to add these keywords. The use of the PPS EXEC and the PPS XEDIT MACRO or the TCP/IP LPR EXEC is the suggested way to add LPR keywords to a spool file for printing.

    The rest of this section describes how to manually add keywords to the beginning of a file prior to printing on a LPR-type link which has been defined with the USer=Yes link parameter.

    Warning!

    Use caution when printing a file which has had keywords added manually to the beginning of a file. If you intend to use the CMS PRINT command, you will need to use the (CC option. Otherwise the RSCS LPR-type link will not find the keywords as the first data records of the spool file.

    Rules for adding keywords to the beginning of files are:

    • All parsing and validations are done by the LPR-type link.
    • Keywords can be anywhere in a record but a valid keyword must be the first non-blank character found on a record.
    • Multiple keywords are allowed per record
    • Valid keywords must precede any data records. Once a data record is found, the LPR-type link will cease looking for keywords.
    • The same keyword can be defined on multiple records. This allows long strings to be split across records.

      For example:

      HOSTNAME=GDLVM7.ENDICOTT.
      HOSTNAME=IBM.COM
      
    • Once the defined string length has been reached for each keyword, any additional keyword data will cause an error message to be issued to the RSCS console and user, and the file to be purged.
    • Not all keywords need be used
    • Only HOSTNAME=, SUFFIX=, PREFIX=, and TRANS= will be checked for valid hexadecimal (0-9, A-F) characters as each record is read. Any errors will cause an error message to be issued to the RSCS console and user, and the file to be purged.
    • HOSTID= will be checked for a valid IP address. Any errors will cause an error message to be issued to the RSCS console and user, and the file to be purged. This keyword cannot span multiple records.
    • See "New and Changed Messages" for a description of message DMTLPR256E which will be issued for any errors found.

    Valid keywords are as follows:

    FILTER=f
    Provide a one-character filter to be used in the control file sent to a remote daemon
    HOSTID=ipaddress
    Provide the host IP address of a remote daemon in dotted decimal
    HOSTNAME=address
    Provide up to 255 characters of a fully-qualified remote daemon host name
    PREFIX=string
    Provide up to 500 characters (250 when packed by RSCS) of a prefix string for the LPRXONE or LPRXPSE sample exits to send to the printer prior to sending data. This string can be used to initialize the printer, such as selecting a paper tray.

    The prefix string can be split with part sent before the separator page and part sent after. The string will be split if the FF04 divider characters are detected within the prefix string. The part before the divider characters will be sent prior to the separator page with the remaining sent after.

    PRINTER=name
    Provide up to 256 characters of a printer queue name
    SEP=string
    Provide a separator page setting for a LPR-type link exit to use.

    The LPRXONE and LPRXPSE sample exits will accept the following settings:

    YES
    Indicates to send an RSCS style separator page in front of the file
    NO
    Indicates not to request or produce a separator
    HOST
    Indicates to include the 'L' control file record requesting a banner page be produced by the remote daemon.
    2P
    Indicates to print a two-page separator page. This is useful in conjunction with duplexing so that the print data starts on a fresh page.
    Any other string settings will be ignored.
    SUFFIX=string
    Provide up to 500 characters (250 when packed by RSCS) of a suffix string for the LPRXONE or LPRXPSE sample exits to send to the printer after sending data. This string can be used to reset the printer state.

    The suffix string can be split with part sent before the trailer page generated by the LPRXPSE and ASCXPSE sample exits and part sent after. The string will be split if the FF04 divider characters are detected within the suffix string. The part before the divider characters will be sent prior to the trailer page with the remaining sent after.

    TRANS=string
    Provide 512 characters for a replacement translate table for LPRXONE or LPRXPSE sample exits to use while printing this file

    System Supplied Keywords

    A new sample exit has been provided in the RSCSEXIT LOADLIB, called LPRXFORM, utilizing exit points 0 and 1. This exit will read an external configuration file defined with a DDNAME of LPRXFORM on a FILEDEF statement in the PROFILE GCS file for the RSCS virtual machine. The exit will build FORM blocks based on keywords provided in the configuration file. These FORM blocks are then authorized for use by LPR-type links using the SYStem=Yes link parameter (see

    Warning!
    The LPRXFORM exit is not intended for use on the EXIT= parameter of a LPR-type link. If used, the link will abend.

    "New Link Parameters"). When files arrive for printing by a LPR-type link with SYStem=Yes, the spool file form name will be used to search for a FORM block built by LPRXFORM. If found, keywords defined will be used as overrides to the link parameter definitions. If not found, the link name will be used to search for a FORM block. This allows the long link parameters, such as host name, prefix, and suffix to be moved from the RSCS configuration file to the LPRXFORM configuration file.

    Rules of the LPRXFORM configuration file are:

    • Each record must start in column one
    • Only one keyword allowed per record
    • The same keyword can be defined on multiple records. This allows long strings to be split across records.

      For example:

      HOSTNAME=GDLVM7.ENDICOTT.
      HOSTNAME=IBM.COM
      
    • Once the defined string length has been reached for each keyword, any additional keyword data will cause an error message to be issued
    • Not all keywords need be used for each FORM block.
    • The FORM= keyword starts a new FORM block and must precede any other keyword. This FORM block name will be checked for uniqueness. If a duplicate is found, or the name exceeds 8 characters, the entire FORMBLOK will be ignored. This keyword cannot span multiple records of a FORM block.
    • An * in column one denotes a comment record.
    • Blank records are not allowed. Each record must contain a valid keyword or be a comment record.
    • The entire file will be read, any errors will generate messages but processing will continue on valid statements, keywords, and forms
    • Only HOSTNAME=, SUFFIX=, PREFIX=, and TRANS= will be checked for valid hexadecimal (0-9, A-F) characters as each record is read. Any errors will cause the record to be ignored and processing to continue.
    • HOSTID= will be checked for a valid IP address. Any errors will cause the record to be ignored and processing to continue. This keyword cannot span multiple records of a FORM block.
    • The LPRXFORM exit routine will always return to RSCS with RC=0.

    Valid keywords are as follows:

    FILTER=f
    Provide a one-character filter to be used in the control file sent to a remote daemon
    FORM=name
    Provide a one- to eight-character name for the FORM block.
    FORMSUB=name
    Provide a one- to eight-character form name to replace the spool file form name. This would provide a form name for use with the LPRXPSE sample exits.
    HOSTID=ipaddress
    Provide the host IP address of a remote daemon in dotted decimal
    HOSTNAME=address
    Provide up to 255 characters of a fully-qualified remote daemon host name
    PREFIX=string
    Provide up to 500 characters (250 when packed by RSCS) of a prefix string for the LPRXONE or LPRXPSE sample exits to send to the printer prior to sending data. This string can be used to initialize the printer, such as selecting a paper tray.

    The prefix string can be split with part sent before the separator page and part sent after. The string will be split if the FF04 divider characters are detected within the prefix string. The part before the divider characters will be sent prior to the separator page with the remaining sent after.

    PRINTER=name
    Provide up to 256 characters of a printer queue name
    SEP=string
    Provide a separator page setting for a LPR-type link exit to use.

    The LPRXONE and LPRXPSE sample exits will accept the following settings:

    YES
    Indicates to send an RSCS style separator page in front of the file
    NO
    Indicates not to request or produce a separator
    HOST
    Indicates to include the 'L' control file record requesting a banner page be produced by the remote daemon.
    2P
    Indicates to print a two-page separator page. This is useful in conjunction with duplexing so that the print data starts on a fresh page.
    Any other string settings will be ignored.
    SUFFIX=string
    Provide up to 500 characters (250 when packed by RSCS) of a suffix string for the LPRXONE or LPRXPSE sample exits to send to the printer after sending data. This string can be used to reset the printer state.

    The suffix string can be split with part sent before the trailer page generated by the LPRXPSE and ASCXPSE sample exits and part sent after. The string will be split if the FF04 divider characters are detected within the suffix string. The part before the divider characters will be sent prior to the trailer page with the remaining sent after.

    TRANS=string
    Provide 512 characters for a replacement translate table for LPRXONE or LPRXPSE sample exits to use when printing this file

    To use the LPRXFORM exit points, add the following to the RSCS CONFIG file:

    EXIT 0 ON LPRXFM00
    EXIT 1 ON LPRXFM01
    

    New Link Parameters

    The following new link parameters have been added:

    • DAYshold= for LPR-type links
    • DNSport= for LPR-, TCPASCII-, and TCPNJE-type links
    • FILehold= for LPR-type links
    • HOSTDafn= for LPR-type links
    • HOSTName= for LPR-, TCPASCII-, and TCPNJE-type links
    • ITO= for LPR-type links
    • SECure= for LPR-type links
    • SIze= for LPR-type links
    • SYStem= for LPR-type links
    • TImeout= for LPR-type links
    • USer= for LPR-type links
    DAYshold=nnn
    Specifies the number of days, 0 to 365, undeliverable files will be placed on hold before requeueing it to a notify link. In order to requeue files to a notify link, a route for *LPRH* must be defined, for example:
    ROUTE *LPRH* TO *LPRHOLD
    
    This parameter must be used in conjunction with an events file entry which periodically changes any files on hold to nohold for the LPR link. If a DAYshold parameter is not specified, the LPR link will continue indefinitely to try to deliver the file. If 0 is specified, the LPR link will requeue files to a notify link every time it places them on hold.
    DNSport=portid
    Specifies the port number on the local system which is running the RSCS Domain Name Server, defaults to 900 if not specified.
    FILehold=No
    FILehold=Yes
    Specifies whether or not to place a file on hold when unable to connect to a remote daemon after approximately 1 minute; the default is No which indicates the LPR link will continue connect attempts until successful or the link is STOPped.

    If defined as yes, the LPR link will attempt to connect to the remote daemon at 1, 2, 4, 8, 16, and 32 second intervals. If still unable to connect, the file will be placed on hold. The RSCS events file can be used to periodically remove hold from all held files for a LPR link. A sample RSCS events file entry which will change all held files to NOHOLD for a LPR-type link with linkname of LPR every 10 minutes would look like:

         *      M:010     *         *      *   CHANGE LPR HOLD NOHOLD
    
    HOSTDafn=name
    Specifies a one- to eight-character name which should be used as the host name portion of the control and data file names. A control or data file name is used within the 'Receive control file' and 'Receive data file' subcommands of the daemon 'Receive job' command. The name should start with "cfa" (control file) or "dfa" (data file) followed by a three digit job number followed by the host name that has constructed the control/data file, as described in RFC 1179.

    RSCS defaults to using the link name for the host name portion of the file name if this parameter is not specified. Certain daemons do not tolerate a name which does not match an existing defined host name. This parameter allows for supplying a defined name instead of using the link name.

    HOSTName=address
    Specifies up to 200 characters of the fully-qualified address of the remote host name to connect to. This host name address will be resolved to an IP address using the RSCS Domain Name Server. This may be overridden on a file by file basis by the LPR- and TCPASCII-type exit routines or can be overridden by the LPRXFORM exit or passed by a user. When overridden, the host name can be up to 255 characters.
    ITO=nnn
    Is a number from 0 to 100 that specifies the Inactivity Time Out value. The ITO value defines the length of time that can occur with no activity (that is, no file transmission or reception) before the link is deactivated. If this parameter is not specified, there is no inactivity time out for this link. If a link is ended because its ITO value has been exceeded, its restart exec will not be processed.

    You can specify the following nnn values:

    0
    If specified, the link will be deactivated when there is no activity on the link. RSCS will first send files that are queued for transmission, or finish reception of the file currently being received, before deactivating the link.
    1-99
    Approximates the number of minutes until the link will be deactivated if there has been no activity on it.
    100
    If specified, no ITO will be in effect; the link will stay active until it is deactivated manually or until an unrecoverable error occurs.
    SECure=Yes
    SECure=No
    Specifies whether to use local ports 721-731 or 1024-2048; The default is Yes, indicating local ports 721-731 are to be used.
    SIze=nnn
    Specifies the maximum number of records the spool file may contain in order to be processed; the default is 0 which indicates no limit. If the number of records exceeds the maximum allowed amount, an error message will be issued to the user and console, and the file will be placed on hold. nnn can be between 0 (no limit) and 1048576 records.
    SYStem=No
    SYStem=Yes
    Specifies whether or not to search for a FORM table provided by the LPRXFORM exit using the FORM the file was spooled with; the default is No. The FORM table provides keywords which define the printer queue name, remote host name or IP address, translation table to use, filter, substitute form to use on the spool file, prefix string, separator page setting, and suffix string to be used when sending the file to a remote daemon, overriding the values defined for the link. For further details on the LPRXFORM exit, see "System Supplied Keywords".
    TImeout=0
    TImeout=nnn
    Specifies the maximum amount of time, in seconds, to wait for a response from the remote host before aborting delivery of the file and placing it on hold. The default is zero indicating to wait indefinitely for a response from the remote host.
    USer=No
    USer=Yes
    Specifies whether or not to allow keywords to be defined and looked for at the beginning of a print file; the default is No. These keywords can define the printer queue name, remote host name or IP address, translation table to use, filter, prefix string, separator page setting, and suffix string to be used when sending the file to a remote daemon, overriding the values defined for the link. For further details on user defined keywords, see "User Supplied Keywords".

    New Exit Parameters

    The following new link exit parameters have been added:

    • Config= for LPDXMANY, LPRXONE, LPRXPSE, ASCXONE, and ASCXPSE exits
    • CONVert= for LPRXONE, and ASCXONE exits
    • EOT= for LPRXPSE, and ASCXPSE exits
    • FILter= for LPRXONE, and LPRXPSE exits
    • FOrm= for LPRXPSE, and ASCXPSE exits
    • PCL= for LPRXONE, and ASCXONE exits
    Config=ddname
    Specifies the ddname which has been defined as an exit configuration file. If the ddname does not exist, the sample exits will pass back a return code to cause the LPD-, LPR-, or TCPASCII-type link to issue an error message and drain. If this exit parameter is not used, a configuration file is not read by the sample exits causing existing defaults to be used for values which can be defined by the configuration file. For further details see:
    CONVert=No
    CONVert=Yes
    Specifies whether or not to allow protocol conversion; the default is No. This function has been added for printers moved from coax connected protocol converters to LAN attached, connected to multiprotocol cards for TCP/IP. Some applications use the functions built in to protocol converters.

    The LPRXONE and ASCXONE sample exits will look for strings starting with a header defined by the PCL exit parameter and ending with the trailing x'4A' character, which surround pairs of bytes that spell out PCL commands. These pairs of bytes will be packed into single bytes that are the equivalent PCL bytes, which are already in ASCII. Multiple PCL strings can be contained in each record of the print file as long as each string contains the X'4A' trailing character.

    In addition, the LPRXONE and ASCXONE sample exits will look for the SCS (SNA Character String) transparency strings contained anywhere within each record. The SCS transparency string is defined with a x'35' followed by a one byte length, followed by data for the defined length that is sent unaltered (not translated). Multiple SCS transparency strings can be contained within a single record.

    EOT=Yes
    EOT=No
    Specifies whether End Of Transmission (EOT) characters should be inserted after the separator page, data file, and trailer page. The default is Yes causing the EOT characters to be inserted.
    FILter=f
    Specifies the printer filter used in the control file sent to the daemon; the default is f. One EBCDIC character is passed. If it is uppercase alphabetic, it will be translated to lowercase. No other validation is performed. This maintains consistency with RFC1179.
    FOrm=OrFnFsLs
    Specifies the default orientation, font name, font size, and additional leading size to use when printing plain text files, overriding the defaults used by the exit. The spool file form name can be used to further override the values specified here.

    Note: The actual fonts selected must be installed and used by the printer.

    The following can be used for OrFnFsLs and shows the default when not specified:

    Or
    File orientation:
    PO
    Portrait (default)
    LA
    Landscape
    Fn
    Font name code
    CB
    Courier-Bold
    CI
    Courier-Oblique
    CP
    Courier (default)
    CX
    Courier-BoldOblique
    HB
    Helvetica-Bold
    HI
    Helvetica-Oblique
    HP
    Helvetica
    HX
    Helvetica-BoldOblique
    SP
    Symbol
    TB
    Times-Bold
    TI
    Times-Italic
    TP
    Times-Roman
    TX
    Times-BoldItalic
    Fs
    Font size, 04 thru 99; the default is 11 for portrait and 10 for landscape orientation
    Ls
    Additional leading size, 0.0 - 9.9, added to font size to give leading, specified as 00 thru 99; the default is 09 for portrait and 12 for landscape
    PCL=string
    Specifies a two- to eight-character string defining the header for PCL strings which the LPRXONE and ASCXONE sample exits will search for in each record of the file to be printed when the CONV=Y exit parameter is specified. An even number of characters must be specified. The default is 6A79.

    Enhanced Exit Parameters

    The existing Sep=, SUFfix=, and Prefix= exit parameters for the LPRXONE, LPRXPSE, ASCXONE, and ASCXPSE exits have been enhanced.

    Sep=2p will produce a two-page separator page. This is useful in conjunction with duplexing so that the print data starts on a fresh page.

    The prefix string can be split with part sent before the separator page and part sent after. The string will be split if the FF04 divider characters are detected within the prefix string. The part before the divider characters will be sent prior to the separator page with the remaining sent after.

    The suffix string can be split with part sent before the trailer page generated by the LPRXPSE and ASCXPSE sample exits and part sent after. The string will be split if the FF04 divider characters are detected within the suffix string. The part before the divider characters will be sent prior to the trailer page with the remaining sent after.


    Exit Configuration Files

    The following LPD-, LPR, and TCPASCII link type exits now support reading an external configuration file:

    • ASCXONE
    • ASCXPSE
    • LPDXMANY
    • LPRXONE
    • LPRXPSE

    LPDXMANY Configuration file

    The LPDXMANY sample exit routine can now read a configuration file. This configuration file can supply overrides for processing when a file is received from a remote LPR command based on the printer queue name. The configuration file can also be used to supply a translate table to override the one used by the exit, and to supply the origin node for spool files LPDXMANY creates.

    The configuration file can have any desired filename and filetype and must be on a disk accessed by the RSCS user ID. This file must be defined with a FILEDEF statement in the PROFILE GCS. The DDNAME used must be supplied on the Config= link exit parameter statement when defining the LPD-type link in the RSCS CONFIG file. For further details on the Config= link exit parameter, see "New Exit Parameters".

    A sample PROFILE GCS DDNAME entry:

    'FILEDEF LPDX DISK LPD CONFIG *'
    
    Where LPDX is the DDNAME defined and LPD CONFIG is the name of the LPDXMANY configuration file.

    A sample RSCS CONFIG parameter (PARM) for an LPD-type link with linkname LPD using the DDNAME defined on the FILEDEF statement in the PROFILE GCS:

    PARM LPD EXIT=LPDXMANY PORT=515 EPARM='C=LPDX'
    

    Layout of the LPDXMANY Configuration File

    An * in column one denotes a comment line. Any line that does not have an * in column one will be interpreted as a configuration entry. All entires must be capitalized and start in column one.

    The following configuration records are supported:

    LOCAL_NODE=string
    Provide a one- to eight-character origin node name LPDXMANY assigns to the created spool file. If this option is not specified, LPDXMANY will use the link name assigned to the LPD-type link as the origin node name.
    TOASCII=string
    Provide a table for EBCDIC to ASCII translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCII= records to replace the 256-byte translation table.
    TOEBCCMD=string
    Provide a table for ASCII to EBCDIC translation of the LPR control file and commands, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOEBCCMD= records to replace the 256-byte translation table.
    TOEBCDIC=string
    Provide a table for ASCII to EBCDIC translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOEBCDIC= records to replace the 256-byte translation table.
    queuename
    Provide the ability to override defaults used by LPDXMANY on a printer queue name basis when receiving a file from a remote host. Multiple, unique, printer queue name records can be specified. The layout of the printer queue name records are as follows:
    • Each queue name option is separated by one or more blanks.
    • The parameters are not column dependent.
    • One record per line, continuation is not supported.
    • Each parameter IS position dependent.
    • An * can be used in a position (other than for the printer queue name) to tell LPDXMANY to use the existing default.
    • The printer queue name will be parsed into user ID and node ID as follows:
      <userid@>nodeid
      <userid%>nodeid
      nodeid
      user ID will be set to SYSTEM.
      @nodeid
      user ID will be set to SYSTEM.
      %nodeid
      user ID will be set to SYSTEM.
      userid@
      node ID will be set to local node name.
      userid%
      node ID will be set to local node name.
      NONEOFTHEABOVE
      node ID and user ID MUST be set within record.
      The userid and nodeid parsed from the printer queue name can be overridden within the record. If both are overridden, the printer queue name is not parsed. If neither are overridden, the printer queue name is parsed into user ID and node ID which must be valid (either of which can still be overridden within).
    The format of the printer queue name records is:
    queuename ppos lpage class forms jobn dest pagination translation userid nodeid tcpxlbin
    DEFAULT ppos lpage class forms jobn dest pagination translation userid nodeid tcpxlbin
    
    queuename
    is a printer queue name up to 32 characters. A queuename of DEFAULT can be used to define parameters for any printer queue not defined by a configuration file record. When a printer queue name arrives, LPDXMANY first looks for a configuration record of that name; if not found it will look for a configuration record using DEFAULT; if not found it will use existing LPDXMANY defaults.
    ppos
    is the logical record length 1-1280; default is 255 The device type LPDXMANY assigns based on the PPOS is as follows:
    PPOS Device Type
    205-1280 VAFP
    151-204 3800
    133-150 3211
    81-132 1403
    1-80 PUNCH
    lpage
    is the number of lines per page 1-99; default is 66
    class
    is the one character spool file class; default is blank
    forms
    is the one- to eight-character spool file form; default is blank
    jobn
    is the one- to eight-character job name; default is SYSTEM
    dest
    is the one- to eight-character PSF destination; default is blank. When using a PSF destination, LPDXMANY will set the user ID field of the tag to SYSTEM.
    When using a PSF destination, the printer queue name can be in the form SYSTEM@nodeid. Alternatively, the printer queue name can be anything unique as long as the user ID field is SYSTEM or * and the node ID field is specified.
    pagination
    is either PAGE or NOPAGE; default is NOPAGE. This parameter determines how pagination will be performed as follows:
    • PAGE will cause LPDXMANY to always paginate regardless of the control file print filter.

    • NOPAGE will cause LPDXMANY to paginate only as defined by the 'f' or 'p' control file print filters. To be effective, the control file must be received prior to the data file.

    translation
    is either TRAN, NOTRAN, or ASISCC; default is TRAN. Translation specifies whether or not to translate the data file prior to spooling as follows:
    TRAN
    Translate data received into EBCDIC removing any CR/LF/FF (carriage return, line feed, form feed) control characters.
    NOTRAN
    Do not translate data received into EBCDIC, but remove any CR/LF/FF (carriage return, line feed, form feed) control characters.
    ASISCC
    Leave the data received as is, do not translate nor remove any control characters. ASISCC would be desired when data received is destined to be printed by a LPR-type link.
    userid
    is the one- to eight-character user ID to which the file should be spooled to; default is derived from the printer queue name.

    Note: If a PSF destination is provided by dest, then the userid field can only be set to SYSTEM.

    nodeid
    is the one- to eight-character destination node ID to which the file should be spooled to; default is derived from the printer queue name.
    tcpxlbin
    is the filename of a TCP/IP TCPXLBIN translate table to be used for this printer queue name. The file must exist on any accessed disk. If not specified, the translation table used will either be the default one within LPDXMANY or the override specified within the LPDXMANY configuration file.
    Some examples:
    LPR@NODEONE 1280 50 * STDN * * * ASISCC ASCII
    LOCALNODE * * * * * SYSTEM
    DEFAULT 255 66 * * SYSTEM * NOPAGE TRAN *
    

    The first example would allow a file to be received without translating, and spooled to a LPR link using the LPRXONE exits causing the file to be sent unaltered to a remote daemon.

    The second example defines a printer queue used to spool input to the system printer.

    The third example shows the defaults defined within LPDXMANY.

    LPRXONE and ASCXONE Configuration file

    The LPRXONE and ASCXONE sample exit routines can now read a configuration file. This configuration file is used to supply the following:

    • Translation tables to override the ones used by the exit.
    • Overrides for the control file created by LPRXONE.

    The configuration file can have any desired filename and filetype and must be on a disk accessed by the RSCS user ID. This file must be defined with a FILEDEF statement in the PROFILE GCS. The DDNAME used must be supplied on the Config= link exit parameter statement when defining the LPR- or TCPASCII-type link in the RSCS CONFIG file. For further details on the Config= link exit parameter, see "New Exit Parameters".

    A sample PROFILE GCS DDNAME entry:

    'FILEDEF LPRONE DISK LPR CONFIG *'
    
    Where LPRONE is the DDNAME defined and LPR CONFIG is the name of the configuration file.

    A sample RSCS CONFIG parameter (PARM) for a LPR-type link with linkname LPR using the DDNAME defined on the FILEDEF statement in the PROFILE GCS:

    PARM LPR EXIT=LPRXONE EPARM='C=LPRONE'
    

    Layout of the LPRXONE and ASCXONE Configuration File

    An * in column one denotes a comment line. Any line that does not have an * in column one will be interpreted as a configuration entry. All entries must be capitalized.

    The following configuration records are supported:

    ASCII=string
    Provide a table for translating ASCII control characters, overriding the default used by the exit. LPRXONE uses this translation table when files are already in ASCII and the user ID field of the TAG is set to 'ASCIIC'. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple ASCII= records to replace the 256-byte translation table.
    DOMAINAME=string
    Used to specify a domain name, up to 255 characters, to be appended after the host name of the 'H' control file record. A period (.) will be inserted between the host name and domain name. This record can be used to add a domain name after the host name, which by default is the node name where the file originated or as specified in the HOSTNAME= record. This record is not supported by the ASCXONE exits.
    HOSTNAME=string
    Used to specify a host name, up to 255 characters, for the 'H' control file record, overriding the default, which is the node name where the file originated. This record is not supported by the ASCXONE exits.
    TOASCII=string
    Provide a table for EBCDIC to ASCII translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCII= records to replace the 256-byte translation table.
    TOASCIIC=string
    Provide a table for EBCDIC to ASCII translation of the LPR control file, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCIIC= records to replace the 256-byte translation table. This record is not supported by the ASCXONE exits.
    USERNAME=string
    Used to specify a user name, up to 32 characters, for the 'P' control file record, overriding the default name used by the exit, which is the user name of the file originator. This record can be used to cause all error messages to be sent to a central location. This record is not supported by the ASCXONE exits.

    LPRXPSE and ASCXPSE Configuration file

    The LPRXPSE and ASCXPSE sample exit routines can now read a configuration file. This configuration file is used to supply the following:

    • Translation table to override the one used by the exit
    • Postscript program to override the one sent to the printer when printing plain text files
    • Additional font names used when printing plain text files.
    • Overrides for the control file created by LPRXPSE.

    The configuration file can have any desired filename and filetype and must be on a disk accessed by the RSCS user ID. This file must be defined with a FILEDEF statement in the PROFILE GCS. The DDNAME used must be supplied on the Config= link exit parameter statement when defining the LPR- or TCPASCII-type link in the RSCS CONFIG file. For further details on the Config= link exit parameter, see "New Exit Parameters".

    A sample PROFILE GCS DDNAME entry:

    'FILEDEF LPRPSE DISK LPR CONFIG *'
    
    Where LPRPSE is the DDNAME defined and LPR CONFIG is the name of the configuration file.

    A sample RSCS CONFIG parameter (PARM) for a LPR-type link with linkname LPR using the DDNAME defined on the FILEDEF statement in the PROFILE GCS:

    PARM LPR EXIT=LPRXPSE EPARM='C=LPRPSE'
    

    Layout of the LPRXPSE and ASCXPSE Configuration File

    An * in column one denotes a comment line. Any line that does not have an * in column one will be interpreted as a configuration entry. All entries must be capitalized.

    The following configuration records are supported:

    DOMAINAME=string
    Used to specify a domain name, up to 255 characters, to be appended after the host name of the 'H' control file record. A period (.) will be inserted between the host name and domain name. This record can be used to add a domain name after the host name, which by default is the node name where the file originated or as specified in the HOSTNAME= record. This record is not supported by the ASCXPSE exits.
    ENCODING=string
    Used to specify an encoding vector to be included with the postscript program sent when printing plain text files. Up to 32-characters can be specified. The default encoding vector used is StandardEncoding.

    Warning: The encoding vector, in many case, is case sensitive. For example, if ISOLatin1Encoding is acceptable to a printer, ISOLATIN1ENCODING may not be.

    FONT=xxname
    Provide a 2-character font name abbreviation (xx) followed by a 32-character font name. There should be no blanks between the abbreviation and full font name. Multiple records can be provided for supplying as many additional fonts as required. The abbreviation should be unique on each FONT= record. In addition, the fonts must be loaded and available at the printer.

    The current available fonts are:

    2-character abbreviation 32-character Font name
    CB Courier-Bold
    CI Courier-Oblique
    CP Courier (exit default)
    CX Courier-BoldOblique
    HB Helvetica-Bold
    HI Helvetica-Oblique
    HP Helvetica
    HX Helvetica-BoldOblique
    SP Symbol
    TB Times-Bold
    TI Times-Italic
    TP Times-Roman
    TX Times-BoldItalic
    HOSTNAME=string
    Used to specify a host name, up to 255 characters, for the 'H' control file record, overriding the default, which is the node name where the file originated. This record is not supported by the ASCXPSE exits.
    PSCRIPT='string'
    Provide a replacement postscript program to be used when printing a plain text file. The postscript program must be enclosed within quotes. Anything after the ending quote will be ignored allowing for comments.

    For example:

    PSCRIPT='this is line one'  comment for line one
    PSCRIPT='this is line two'
    
    Multiple PSCRIPT= records can be provided in order to supply the entire program. LPRXPSE will add a carriage return (X'0A') after each record, and will translate the record from EBCDIC to ASCII.

    Note: When replacing the postscript program, the ability to tailor the file orientation, font name, font size, and additional leading size through a FORM is lost. The supplied postscript program must define all of these.

    TOASCII=string
    Provide a table for EBCDIC to ASCII translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCII= records to replace the 256-byte translation table.
    TOASCIIC=string
    Provide a table for EBCDIC to ASCII translation of the LPR control file, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCIIC= records to replace the 256-byte translation table. This record is not supported by the ASCXPSE exits.
    USERNAME=string
    Used to specify a user name, up to 32 characters, for the 'P' control file record, overriding the default name used by the exit, which is the user name of the file originator. This record can be used to cause all error messages to be sent to a central location. This record is not supported by the ASCXPSE exits.

    LPR-type Link Exit Parameter List

    The parameter list passed to each LPR-type link exit routine has been expanded as follows:

    Word 11 (+40)
    Address of a 255-character host name
    Word 12 (+44)
    Address of a full word containing the length of a user defined prefix string followed by the 250-byte prefix string
    Word 13 (+48)
    Address of a full word containing the length of a user defined suffix string followed by the 250-byte suffix string
    Word 14 (+52)
    Address of a one-character user defined filter
    Word 15 (+56)
    Address of a 256-character user defined translate table
    Word 16 (+60)
    Address of a 4-character user defined separator page setting

    New and Changed Messages

    012ILink linkid exit routine name loaded at address

    Explanation: An exit module has been loaded for use by the indicated ASCII-, LPR-, TCPASCII-, UFT-, or UFTD-type link. The linkid identifies the link. The routine is identified by its entry point name name and is loaded at address, the hexadecimal storage address.

    System Action: Normal system operation continues.

    Operator Response: None.

    Destination: R, SCO

    193ILink linkid {connecting to | disconnecting from | unable to connect to} host ip-address port port { printer printer | user username }

    Explanation: This message is issued when a LPR- of UFT-type link attempts to connect to, disconnect from, or has been unable to connect to, the indicated host. "Connecting to" indicates a file has arrived on the link to be transmitted. "Disconnecting from" indicates the file is finished processing. "Unable to connect to" indicates the link has been defined with the FILehold=Yes parameter and has attempted for approximately 1 minute to connect with the indicated host.

    linkid
    Link identifier of the LPR- or UFT-type link sending the file.
    ip-address
    IP address of the host to which the link is connecting, disconnecting, or unable to connect to.
    port
    Port number to which the link is connecting, disconnecting, or unable to connect to.
    printer
    Name of the printer queue on the host where the file will be sent for LPR-type links.
    username
    Name of the user ID on the host where the file will be sent for UFT-type links.

    System Action: Normal RSCS processing continues. If the link was unable to connect to the indicated host, the file being processed is put on hold.

    Operator Response: If the link was defined with the FILehold=Yes parameter, an entry should be included in the RSCS event file to periodically change all held files for the indicated link to NOHOLD.

    Destination: R, SCO

    215ILink linkid response message requested by {data | control | command} exit, message=message

    Explanation: One of the following return codes was provided by the exit routines while a LPD- or UFTD-type link was processing a data stream from a TCP/IP line print router or unsolicited file transfer client:

    • A return code of 8 was returned by the data processing exit routine for a LPD-type link.
    • A return code of 8 was returned by the control file exit routine for a LPD-type link.
    • A return code of 12 was returned by the data processing exit for a UFTD-type link.
    • A return code of 8 or 12 was returned by the UFT command processing exit for a UFTD-type link.
    This return code requests RSCS to send a negative response message provided by the exit routine to the TCP/IP LPR or UFT client.
    linkid
    Specifies the link identifier of the link receiving the file.
    message
    The negative response message returned by the exit routine.

    System Action: The negative response message is sent to the TCP/IP LPR or UFT client, the spool file is purged if created, and the connection with the TCP/IP client is closed.

    Operator Response: If the problem persists, start local diagnostic procedures to determine why the exit is sending a negative response message.

    Destination: R

    256ELink linkid keyword keyword {missing | data invalid | not allowed} for file fileid -- file purged

    Explanation: This message is issued when a LPR- or UFT-type link has detected an error in a user supplied keyword. The keyword and possible errors are as follows:

    DESTADDR=
    Either the destination address (username and hostname) provided exceeds 255 characters, one has not been provided by the user for a UFT-type link, or name resolution failed for the hostname portion.
    FILTER=
    The filter provided exceeds 1 character in length.
    HOSTNAME=
    Either the host name provided exceeds 255 characters, one has not been provided by the user or defined for the link, or name resolution failed.
    HOSTID=
    The host ID in dotted decimal is not valid or exceeds 16 characters.
    PREFIX=
    Either the prefix string provided exceeds 500 characters, does not contain valid hexadecimal characters (0-9, A-F), or is an odd number of characters.
    PRINTER=
    Either the printer queue name provided exceeds 256 characters or one has not been provided by the user or defined for the link.
    SEP=
    The separator string provided exceeds 4 characters in length.
    SUFFIX=
    Either the suffix string provided exceeds 500 characters, does not contain valid hexadecimal characters (0-9, A-F), or is an odd number of characters.
    TRANS=
    Either the translate table provided does not contain 512 characters, or does not contain valid hexadecimal characters (0-9, A-F).
    TRANSLATE=
    Either the translate table provided does not contain 512 characters, or does not contain valid hexadecimal characters (0-9, A-F).
    TRANSFORM=
    The UFT transform type specified is not supported by the UFT-type link.
    The LPR- or UFT-type link detected one of the following possible errors with the user supplied keyword:
    missing
    The keyword is required for the LPR- or UFT-type link and has not been specified by the user or as a link parameter.
    data invalid
    The LPR- or UFT-type link detected an error with the associated data supplied with the indicated keyword.
    not allowed
    A keyword has been detected by an LPR- or UFT-type link which was defined not to allow user keywords (USer=No). In this instance, the file will be rejected for security reasons since it may not be printed where the user intended.

    This message is also issued when a keyword has been detected by an LPR-type link which was defined not to allow user keywords (USer=No). In this instance, the file will be rejected for security reasons since it may not be printed where the user intended.

    System Action: The file is purged.

    User Response: Correct the problem with the indicated keyword and resubmit the file for printing, or contact your local RSCS administrator.

    Destination: R, SCO

    257IEnablement verification check returned {not enabled | not defined | an unknown error} -- {RSCS initialization continuing | TCP Port redirector not started | RSCS/VTAM interface not started}

    Explanation: This message is issued if RSCS detects it is running in a disabled state during initialization, or when the TCP START OR NET START commands have been issued.

    System Action: If issued during initialization, RSCS processing will continue. If issued as a result of the TCP START or NET START commands, those commands will fail and the resulting task will not be started.

    User Response: If the TCP port redirector, RSCS/VTAM interface, or the indicated link are required, then RSCS must be licensed and enabled on your system. If RSCS is licensed, process the enabling instructions in section 6.1 of the RSCS program directory.

    Destination: RO, SCO

    258IEnablement verification check returned {not enabled | not defined | an unknown error} -- link linkid not started

    Explanation: This message is issued if RSCS detects it is running in a disabled state while processing a START command for a link which does not support new function for the TCP/IP feature of VM/ESA 2.3.0, 2.4.0, or z/VM.

    System Action: The indicated link will not be started.

    User Response: If the indicated link is required, then RSCS must be licensed and enabled on your system. If RSCS is licensed, process the enabling instructions in section 6.1 of the RSCS program directory.

    Destination: RO, SCO

    259ELink linkid device address nnnn is not a TN3270E attached printer

    Explanation: This message is issued if RSCS detects that a TN3270E-type link is not a TELNET printer attached by the TCP/IP feature of VM/ESA 2.3.0, 2.4.0, or z/VM.

    System Action: The indicated link will not be started.

    User Response: If the indicated link is required, then it must be defined and attached to RSCS by the TCP/IP feature of VM/ESA 2.3.0, 2.4.0, or z/VM.

    Destination: RC, SCO

    260ELink linkid {CONNECT | TAG} processing exit has rejected file origid

    Explanation: Either the CONNECT processing exit routine for a UFTD-type link has rejected a UFT clients request to send a file, or the TAG processing exit routine for a UFT-type link has rejected the file identified by origid. Either exit does this by returning to RSCS with a return code of 4.

    Reasons the UFTXOUT exit routines may reject a file include:

    • The logical record length was not provided for transformation type VARREC.
    • The logical record length provided for transformation type VARREC is greater than 65535 bytes.
    • The transformation type is not supported.

    System Action: The file is purged.

    Operator Response: If the file rejection is viewed as a problem, notify the local support personnel responsible for the exit that rejected the file.

    Destination: R, RS

    262ELink linkid file spoolid not in the required NETDATA format -- file purged

    Explanation: This message is issued when an UFT-type link has not been able to find NETDATA control records in the indicated spool file.

    System Action: The file is purged.

    User Response: The CMS SENDFILE COMMAND should be used to send a file on a RSCS UFT link. Review the help file for the SENDFILE command then resubmit the file for processing, or contact your local RSCS administrator.

    Destination: R, SCO


    The PPS Command

     
                           +-?---------------------------------------------------------------------+
                           |                                                                       |
                           |                                                                       |
                 >>--PPS---+-+-------------------+-+---------------------------------------------+-+--><
                             |                   | |                                             |
                             |       +-PS *------+ |      +--------------------------+           |
                             +-fn----+-----------+ |      V                          |           |
                                     |   +-*--+ |  +--(---+-COpy--+-nnn-+----------+-+--+-----+--+
                                     +-ft+----+-+         |       |     |          |    |     |
                                         +-fm-+           |       +-.---+          |    +--)--+
                                                          |-Cc---------------------|
                                                          |-Font--+-name-+---------|
                                                          |       |      |         |
                                                          |       +-.----+         |
                                                          |-FILter--+-f-+----------|
                                                          |         |   |          |
                                                          |         +-.-+          |
                                                          |-FORm--+-name-+---------|
                                                          |       |      |         |
                                                          |       +-.----+         |
                                                          |-HOSTId--+-ipaddress-+--|
                                                          |         |           |  |
                                                          |         +-.---------+  |
                                                          |-HOSTName--+-address-+--|
                                                          |           |         |  |
                                                          |           +-.-------+  |
                                                          |-JOB--+-name-+----------|
                                                          |      |      |          |
                                                          |      +-.----+          |
                                                          |-LAndscape--------------|
                                                          |-Leading--+-nn-+--------|
                                                          |          |    |        |
                                                          |          +-.--+        |
                                                          |-NIckname--+-name-+-----|
                                                          |           |      |     |
                                                          |           +-.----+     |
                                                          |-Nocc-------------------|
                                                          |-NODe--+-name-+---------|
                                                          |       |      |         |
                                                          |       +-.----+         |
                                                          |-POrtrait---------------|
                                                          |-PREfix--+-string-+-----|
                                                          |         |        |     |
                                                          |         +-.------+     |
                                                          |-Printer--+-name-+------|
                                                          |          |      |      |
                                                          |          +-.----+      |
                                                          |-PRINTQueue--+-name-+---|
                                                          |             |      |   |
                                                          |             +-.----+   |
                                                          |-Rscs--+-userid-+-------|
                                                          |       |        |       |
                                                          |       +-.------+       |
                                                          |-SEP--+-string-+--------|
                                                          |      |        |        |
                                                          |      +-.------+        |
                                                          |-Size--+-nn-+-----------|
                                                          |       |    |           |
                                                          |       +-.--+           |
                                                          |-SUFfix--+-string-+-----|
                                                          |         |        |     |
                                                          |         +-.------+     |
                                                          |-TAG--+-'tag_options'-+-|
                                                          |      |               | |
                                                          |      +-.-------------+ |
                                                          |-TCPXlbin--+-fn-+-------|
                                                          |           |    |       |
                                                          |           +-.--+       |
                                                          +-TRAns--+-string-+------+
                                                                   |        |
                                                                   +-.------+
    

    Purpose

    The PPS command can be used from the CMS ready prompt to send files, including Postscript files, to an RSCS LPR-type link using the LPRXONE or LPRXPSE sample exit routines, or to an RSCS TCPASCII-type link using the ASCXONE or ASCXPSE sample exit routines.

    Parameters

    ?
    Will cause a short help describing the exec input parameters to be displayed. This is the default if the exec is issued without any command parameters.
    fn
    Is the filename of the file to print.
    PS
    ft
    Is the filetype of the file to print. If not specified, the filetype will default to PS.
    *
    fm
    Is the filemode of the file to print. If not specified, the first occurrence of the filename and filetype on any accessed disk will be printed.
    COpy nnn
    Identifies the number of copies to be printed, specified as 1 to 255; the default is 1.
    Cc
    Indicates the file to be printed already contains carriage control characters in column one of each record. This is the default for filetypes of LISTING.
    FILter f
    Provides a one-character print filter used in the control file sent to the remote daemon.
    Font name
    Is the two-character font name to be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link. See usage note 5 for a list of available font names.
    FORm name
    Provides a one- to eight-character name used as the form when the file is spooled to RSCS for printing.

    Note: FORm is not applicable, nor used, when the Font, LAndscape, Leading, POrtrait, or Size operands are specified.

    HOSTId idaddress
    Provides the host IP address of a remote daemon in dotted decimal.
    HOSTName address
    Provides up to 255 characters of a remote daemon host name.
    JOB name
    Provides a one to eight-character job name or additional job information. The default is the file name. Depending on the LPR server, this allows job information to be printed on the burst page. The job name will also be used for the name of the source file by the LPRXONE and LPRXPSE sample exits.
    LAndscape
    Indicates the file should be printed in landscape mode. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    Leading nn
    Is the two-digit additional leading size, 0.0 - 9.9, specified as 00 to 99, added to the font size to give leading. The default is 09 for portrait and 12 for landscape orientation. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    NIckname name
    Is the nickname within an RSCS NAMES file containing additional keywords to be used when printing a file. This parameter is only valid for print files destined to an LPR-type link using the USer=Yes link parameter. See usage note 6 for a list of available keyword tag/value pairs.
    Nocc
    Indicates the file to be printed does not contain carriage control characters in column one of each record. This is the default for all filetypes except LISTING.
    NODe name
    Is the name of the node where the printer is located. If not specified, it is assumed the printer is attached to the local RSCS node.
    POrtrait
    Indicates the file should be printed in portrait mode. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    PREfix string
    Provides up to 500 characters (250 when packed by RSCS) of a prefix string for the LPRXONE or LPRXPSE sample exits to send to the printer prior to sending the data. This string can be used to initialize the printer, such as selecting a paper tray.

    The prefix string can be split with part sent before the separator page and part sent after. The string will be split if the FF04 divider characters are detected within the prefix string. The part before the divider characters will be sent prior to the separator page with the remaining sent after.

    Printer name
    Is the name of an RSCS LPR-type or TCPASCII-type link. This option must be specified on the command invocation, in lasting globalv, or within the selected nickname in the RSCS NAMES file.
    PRINTQueue name
    Provides up to 256 characters of a printer queue name.
    Rscs userid
    Is the user ID of the virtual machine running RSCS. If not specified, this field will default to the user ID returned from the CMS IDentify command.
    SEP string
    Provide a separator page setting for a LPR-type link exit to use.

    The LPRXONE and LPRXPSE sample exits will accept the following settings:

    YES
    Indicates to send an RSCS style separator page in front of the file
    NO
    Indicates not to request or produce a separator
    HOST
    Indicates to include the 'L' control file record requesting a banner page be produced by the remote daemon.
    2P
    Indicates to print a two-page separator page. This is useful in conjunction with duplexing so that the print data starts on a fresh page.
    Any other string settings will be ignored.
    Size nn
    Is the two-digit font size, from 04 to 99. The default is 11 for portrait and 10 for landscape orientation. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    SUFfix string
    Provides up to 500 characters (250 when packed by RSCS) of a suffix string for the LPRXONE or LPRXPSE sample exits to send to the printer after sending the data. This string can be used to reset the printer state.

    The suffix string can be split with part sent before the trailer page generated by the LPRXPSE and ASCXPSE sample exits and part sent after. The string will be split if the FF04 divider characters are detected within the suffix string. The part before the divider characters will be sent prior to the trailer page with the remaining sent after.

    TAG 'tag_options'
    Can be any valid RSCS accepted TAG options. If this operand is supplied, the data must start with the TAG priority option.

    Note: All characters between the quote immediately following the TAG operand and the last quote on the command invocation will become the tag_options

    An example use on the command line would be:

    TAG '50 (ACCMSG=YES'
    

    An example use within an RSCS NAMES file would be:

    :TAG.50 (ACCMSG=YES
    

    Note: Quotes should not be supplied on the :TAG. nickname entry.

    TCPXlbin fn
    Provides the filename of a TCP/IP TCPXLBIN file containing a translation table for LPRXONE or LPRXPSE sample exits to use when printing this file.
    TRAns string
    Provides 512 characters for a replacement translate table for LPRXONE or LPRXPSE sample exits to use when printing this file.

    Usage

    1. Issuing the PPS EXEC without specifying any parameters will cause a short help describing the exec input parameters to be displayed, as if the ? parameter was used.
    2. LASTING GLOBALV can be used to save optional parameters. If the PPS EXEC is issued with only optional parameters (that is no filename is provided to print), any specified optional parameters will be saved in LASTING GLOBALV.

      When the PPS EXEC is issued, optional parameters will be obtained from LASTING GLOBALV. Values saved in LASTING GLOBALV can be overridden by specifying optional parameters when issuing the PPS EXEC.

    3. For those options which have a keyword/value pair, the use of a period (.) can be used to remove the keyword/value pair from LASTING GLOBALV.
    4. The first record of a file will be examined for the postscript identifier (%!PS) in both ASCII and EBCDIC. If found at the beginning of the record, it's assumed the file is postscript. The file will be packed into blocks of 80 bytes with line feeds separating the records, prior to issuing the CMS PUNCH command.
    5. The following describes the available font names which can be used when printing text files to a postscript printer on a LPR-type link using the LPRXPSE sample exits or a TCPASCII-type link using the ASCXPSE sample exits:
      Fn
      Font name code
      CB
      Courier-Bold
      CI
      Courier-Oblique
      CP
      Courier (exit default)
      CX
      Courier-BoldOblique
      HB
      Helvetica-Bold
      HI
      Helvetica-Oblique
      HP
      Helvetica
      HX
      Helvetica-BoldOblique
      SP
      Symbol
      TB
      Times-Bold
      TI
      Times-Italic
      TP
      Times-Roman
      TX
      Times-BoldItalic
    6. The NIckname parameter can be used to specify a nickname tag within an RSCS NAMES file on any accessed disk containing additional keywords which can be used when printing a file to an LPR-type link. These keywords will be placed as No-Operational records at the beginning of the spool file. The LPR-type link which the file is printed on must have the link parameter USer=Yes specified in order for these keywords to be used.

      The keywords are standard :tag.value pairs after a :nick.name, where name is provided with the NIckname parameter. All PPS EXEC operands, except NIckname can be placed within the RSCS NAMES file.

      The nickname file can be used to specify keywords, such as :TRANS., which are too long to include on the PPS EXEC command invocation or within LASTING GLOBALV.

      Rules for the RSCS NAMES file:

      • File can be on any accessed disk.
      • Any non-blank character preceding the colon (:) will cause the line to become a comment and not processed or used.
      • Each record will be uppercased before processing, except for the :FILTER., :HOSTNAME., and :PRINTQUEUE. tag data which will be left as specified.
      • The same keyword can be used multiple times within a nickname tag for a keyword/value pair longer than will fit on one record. For example:
        :TRANS.100 characters of the translate table
        :TRANS.100 characters of the translate table
        :TRANS.100 characters of the translate table
        :TRANS.100 characters of the translate table
        :TRANS.112 characters of the translate table
        
      • Keywords must be fully specified, no abbreviations.
      • Available keywords are as follows:
        • :COPY.nnn
        • :CC.
        • :FILTER.f
        • :FONT.name
        • :FORM.name
        • :HOSTID.idaddress
        • :HOSTNAME.address
        • :JOB.name
        • :LANDSCAPE.
        • :LEADING.nn
        • :NOCC.
        • :NODE.name
        • :PORTRAIT.
        • :PREFIX.string
        • :PRINTER.name
        • :PRINTQUEUE.name
        • :RSCS.userid
        • :SEP.string
        • :SIZE.nn
        • :SUFFIX.string
        • :TCPXLBIN.fn
        • :TAG.tag_options
        • :TRANS.string
    7. Any options specified on the command invocation will override LASTING GLOBALV settings which will override nickname tag settings.


    The PPS XEDIT Macro

     
                                    +---------------------+
                                    V                     |
                        >>--PPS--+--+---------------------+---+--><
                                 |  |                     |   |
                                 |  |-COpy --nnn----------|   |
                                 |  |-Cc------------------|   |
                                 |  |-FILter --f----------|   |
                                 |  |-Font --name---------|   |
                                 |  |-FORm --name---------|   |
                                 |  |-HOSTId --ipaddress--|   |
                                 |  |-HOSTName --address--|   |
                                 |  |-JOB --name----------|   |
                                 |  |-LAndscape-----------|   |
                                 |  |-Leading --nn--------|   |
                                 |  |-NIckname --name-----|   |
                                 |  |-Nocc----------------|   |
                                 |  |-NODe --name---------|   |
                                 |  |-POrtrait------------|   |
                                 |  |-PREfix --string-----|   |
                                 |  |-Printer --name------|   |
                                 |  |-PRINTQueue --name---|   |
                                 |  |-Rscs --userid-------|   |
                                 |  |-SEP --string--------|   |
                                 |  |-Size --nn-----------|   |
                                 |  |-SUFfix --string-----|   |
                                 |  |-TAG --'tag_options'-|   |
                                 |  |-TCPXlbin --fn-------|   |
                                 |  +-TRAns --string------+   |
                                 |                            |
                                 +-?--------------------------+
    

    Purpose

    The PPS XEDIT macro can be used from within the XEDIT environment to send files, including Postscript files, to an RSCS LPR-type link using the LPRXONE or LPRXPSE sample exit routines, or to an RSCS TCPASCII-type link using the ASCXONE or ASCXPSE sample exit routines.

    Parameters

    ?
    Will cause a short help describing the XEDIT macro input parameters to be displayed.
    COpy nnn
    Identifies the number of copies to be printed, specified as 1 to 255; the default is 1.
    Cc
    Indicates the file to be printed already contains carriage control characters in column one of each record. This is the default for filetypes of LISTING.
    FILter f
    Provides a one-character print filter used in the control file sent to the remote daemon.
    Font name
    Is the two-character font name to be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link. See usage note 5 for a list of available font names.
    FORm name
    Provides a one- to eight-character name used as the form when the file is spooled to RSCS for

    Note: FORm is not applicable, nor used, when the Font, LAndscape, Leading, POrtrait, or Size operands are specified.

    HOSTId idaddress
    Provides the host IP address of a remote daemon in dotted decimal.
    HOSTName address
    Provides up to 255 characters of a remote daemon host name.
    JOB name
    Provides a one to eight-character job name or additional job information. The default is the file name. Depending on the LPR server, this allows job information to be printed on the burst page. The job name will also be used for the name of the source file by the LPRXONE and LPRXPSE sample exits.
    LAndscape
    Indicates the file should be printed in landscape mode. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    Leading nn
    Is the two-digit additional leading size, 0.0 - 9.9, specified as 00 to 99, added to the font size to give leading. The default is 09 for portrait and 12 for landscape orientation. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    NIckname name
    Is the nickname within an RSCS NAMES file containing additional keywords to be used when printing a file. This parameter is only valid for print files destined to an LPR-type link using the USer=Yes link parameter. See usage note 6 for a list of available keyword tag/value pairs.
    Nocc
    Indicates the file to be printed does not contain carriage control characters in column one of each record. This is the default for all filetypes except LISTING.
    NODe name
    Is the name of the node where the printer is located. If not specified, it is assumed the printer is attached to the local RSCS node.
    POrtrait
    Indicates the file should be printed in portrait mode. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    PREfix string
    Provides up to 500 characters (250 when packed by RSCS) of a prefix string for the LPRXONE or LPRXPSE sample exits to send to the printer prior to sending the data. This string can be used to initialize the printer, such as selecting a paper tray.

    The prefix string can be split with part sent before the separator page and part sent after. The string will be split if the FF04 divider characters are detected within the prefix string. The part before the divider characters will be sent prior to the separator page with the remaining sent after.

    Printer name
    Is the name of an RSCS LPR-type or TCPASCII-type link. This option must be specified on the macro, in LASTING GLOBALV, or within the selected nickname in the RSCS NAMES file.
    PRINTQueue name
    Provides up to 256 characters of a printer queue name.
    Rscs userid
    Is the user ID of the virtual machine running RSCS. If not specified, this field will default to the user ID returned from the CMS IDentify command.
    SEP string
    Provide a separator page setting for a LPR-type link exit to use.

    The LPRXONE and LPRXPSE sample exits will accept the following settings:

    YES
    Indicates to send an RSCS style separator page in front of the file
    NO
    Indicates not to request or produce a separator
    HOST
    Indicates to include the 'L' control file record requesting a banner page be produced by the remote daemon.
    2P
    Indicates to print a two-page separator page. This is useful in conjunction with duplexing so that the print data starts on a fresh page.
    Any other string settings will be ignored.
    Size nn
    Is the two-digit font size, from 00 to 99. The default is 11 for portrait and 10 for landscape orientation. This option can be used when printing plain text files to a postscript printer when using the LPRXPSE sample exits for a LPR-type link or the ASCXPSE sample exits for a TCPASCII-type link.
    SUFfix string
    Provides up to 500 characters (250 when packed by RSCS) of a suffix string for the LPRXONE or LPRXPSE sample exits to send to the printer after sending the data. This string can be used to reset the printer state.

    The suffix string can be split with part sent before the trailer page generated by the LPRXPSE and ASCXPSE sample exits and part sent after. The string will be split if the FF04 divider characters are detected within the suffix string. The part before the divider characters will be sent prior to the trailer page with the remaining sent after.

    TAG 'tag_options'
    Can be any valid RSCS accepted TAG options. If this operand is supplied, the data must start with the TAG priority option.

    Note: All characters between the quote immediately following the TAG operand and the last quote on the command invocation will become the tag_options

    An example use on the command line would be:

    TAG '50 (ACCMSG=YES'
    

    An example use within an RSCS NAMES file would be:

    :TAG.50 (ACCMSG=YES
    

    Note: Quotes should not be supplied on the :TAG. nickname entry.

    TCPXlbin fn
    Provides the filename of a TCP/IP TCPXLBIN file containing a translation table for LPRXONE or LPRXPSE sample exits to use when printing this file.
    TRAns string
    Provides 512 characters for a replacement translate table for LPRXONE or LPRXPSE sample exits to use when printing this file.

    Usage

    1. When the PPS XEDIT macro is issued, optional parameters will be obtained from LASTING GLOBALV. These values must have been previously saved using the CMS PPS EXEC command. Values saved in LASTING GLOBALV can be overridden by specifying optional parameters when issuing the PPS XEDIT macro.
    2. The same usage notes apply for the PPS XEDIT macro as for the PPS command starting with usage note 4.


    Configuring an RSCS TN3270E Printer Link

    Important!
    A TCP/IP Function Level supplied with VM/ESA 2.3.0, 2.4.0, or z/VM is required in order to use TN3270E-type links.

    The TN3270E protocol supported by TCP/IP provides for the creation of 3270 printer sessions in addition to traditional display sessions. To make this capability available, the following steps must be performed:

    1. An arbitrary name, called the "LU name" must be defined in the TN3270E control statement in the PROFILE TCPIP file. This statement assigns a virtual line address to the printer session.
    2. The TN3270E Printer Management exit must be enabled by the TN3270EEXIT parameter of the INTERNALCLIENTPARMS statement in the PROFILE TCPIP file.
    3. An RSCS TN3270E link must be defined that has a line address that matches the line address defined in step 1. While not required, you may find administration and problem determination easier if the LU name is the same as the associated RSCS link name.

      To configure an RSCS TN3270E printer link, you will need to add LINKDEFINE and PARM configuration file statements in an RSCS configuration file. You will need to define as many of these links as you have defined printer LUNAMES within the PROFILE TCPIP configuration file.

      The RSCSTCP SCONFIG file located on the TCPMAINT 198 minidisk contains a sample LINKDEFINE and PARM statement for a TN3270E-type link. You may wish to rename this sample configuration file as RSCSTCP CONFIG on the TCPMAINT 198 minidisk, have the RSCS machine link the TCPMAINT 198, and imbed this file in the RSCS CONFIG file. Link the TCPMAINT 198, access the TCPMAINT 198 minidisk in the PROFILE GCS, and imbed this file in the RSCS CONFIG file. This way your TCP/IP administrator can configure TN3270E printers in both the PROFILE TCPIP and RSCSTCP CONFIG file by accessing one disk.

    4. The user must have the "LU name" configured in their TN3270E-capable emulator.

    LINKDEFINE and DEFINE Statements for a TN3270E-Type Link

    The LINKDEFINE and DEFINE statements for the TN3270E link driver are defined with the type TN3270E. All existing parameters descriptions can be found in the VM/Remote Spooling Communications Subsystem Planning and Installation and VM/Remote Spooling Communications Subsystem Operation and Use manuals.

    You will need to provide the LINE vaddr parameter on either the LINKDEFINE configuration statement or DEFINE command, or when starting the link. vaddr specifies the 4-digit virtual device number of a TN3270E printer associated with the TN3270E-type link. Valid addresses are X'0002' to X'FFFF'.

    PARM Statement for a TN3270E-Type Link

    The PARM statement for a TN3270E-type link supports the same operands as the PARM statement for a 3270P-type link, with differences in the defaults when not specified, plus the addition of MSG, PRTWtm and PRTRet operands. The following describe the default differences and the new operands:

    COMP=No
    The default is No, indicating the link will not perform blank compression.
    EPC=No
    The default is No, indicating Early Print complete will not be used by the link.
    ITO=0
    The default is 0, indicating the link will drain immediately after the last queued file is processed.
    Msg=
    Specifies if RSCS will allow the TN3270E-type link to dequeue messages destined for transmission to the printer.
    Yes
    RSCS will select all messages for transmission; this is the default.
    No
    RSCS will select messages, but they will not be sent to the printer; the messages will be purged.
    PRTWtm=nnn
    The time, in seconds (1-600), between recovery attempts due to an unattached device. If not specified, the default is 10 seconds.
    PRTRet=nn
    The number of hours (1-100) the link will attempt error recovery due to an unattached device before terminating. If not specified, the default is 1 hour.
    SEP=No
    The default is No, indicating no separator pages will be sent to the printer prior to printing a file.

    Tag Options for a TN3270E-Type Link

    The TN3270E link will accept the same tag options as defined for a 3270P-type link described in the VM/Remote Spooling Communications Subsystem Operation and Use manual except only SOSI2 will be supported for the PRMODE= option.


    UFT Support

    The Unsolicited File Transfer (UFT) support within RSCS 3.2.0 provides two new link drivers:

    • The UFT-type (Unsolicited File Transfer Client) provides support for the UFTASYNC option of the CMS SENDFILE command, enabling files to be transmitted to a remote system when possible, without tieing up the user's CMS session. The required TCP/IP UFT support in SENDFILE is provided with VM/ESA 2.3.0, 2.4.0, or z/VM. In addition, this link driver is accessible to any connected NJE node whether it be another RSCS, VSE/ESA, OS/390, or like peer.
    • The UFTD-type (Unsolicited File Transfer Daemon) enables RSCS to receive files over the internet for delivery to a local VM user, a remote NJE node, locally or remotely attached printer (including LPR-type printer links), or to a UFT-type link.

    The RSCS configuration file LINKDEFINE statement and the RSCS DEFINE and START commands have been updated to accept UFT and UFTD as link types. Line addresses are not required. See "Parm Statement for a UFT-Type Link" and "Parm Statement for a UFTD-Type Link" for further information on the UFT and UFTD configuration file PARM statements. See "Start Command Parameters for a UFT-Type Link" and "Start Command Parameters for a UFTD-Type Link" for further information on the UFT and UFTD START command PARM operands.

    Exit routines are required for both the UFT- and UFTD-type links. See "UFTXOUT Routine", and "UFTXIN Routine" for further information on the IBM-supplied UFT and UFTD exit routines.

    UFT-type Link Driver

    A UFT client driver that enables RSCS to send files to a remote TCP/IP UFT server for distribution to a user, acting as a sendfile gateway between the RSCS NJE world to the TCP/IP UFT world. The UFT-type link is single threaded handling ONE file at a time although successive files may be delivered to different hosts and user IDs by starting multiple UFT-type links and having them be members of an RSCS GROUP.

    The UFT-type link provides I/O, protocol, and error handling. All policy decisions (for example character set translation from EBCDIC to ASCII or binary) are handled by exits. Single threaded handling keeps the writing of exit routines from getting overly complicated.

    UFTD-type Link Driver

    A UFT server, or daemon, driver that enables RSCS to receive files from a TCP/IP UFT client for delivery to a network destination or printer, acting as a gateway for processing files from the TCP/IP world to the NJE world through RSCS.

    The UFTD-type link driver only handles a single file at a time. Since the driver has been designed to allow multiple listens on the same TCP/IP port number, more than one UFTD-type link driver can be started to handle multiple concurrent incoming files.

    The UFTD-type link driver binds to well known port 608 and listens for TCP/IP UFT clients to connect and send a file. The port number that the UFTD-type link driver listens on can be overridden by defining a different port number on the UFTD-type link PARM statement or when starting an UFTD-type link. This allows for site installation testing and more flexibility.

    The maximum data length supported when receiving any individual file by the UFTD-type link driver is 2,147,483,647 bytes (2 giga-bytes).

    This link driver is an input only driver. No data or messages will be transferred out over this link. Only data is transferred in. Any files or messages queued to this link will remain so until explicitly transferred or purged. Use RSCS routing capabilities to avoid having files or messages queued to this link. For example, add the following route to the RSCS configuration file to cause files or messages bound to an UFTD link to instead be queued on a notify link:

    ROUTE UFTD TO *UNKNOWN
    

    TCP/IP Machine Configuration file

    If you currently are using VM TCP/IP UFTD as your VM UFT daemon and wish to replace this with RSCS's UFTD link driver, then you will need to make the following changes in the TCP/IP machines configuration file:

    • Remove UFTD from the autolog list
    • Change UFTD to RSCS for the port 608 reserve list
    • Define UFTD link in RSCS with the appropriate exit (customize if appropriate to match the UFTD Configuration).

    Note: In order to test the RSCS UFTD-type link, you will first need to shutdown UFTD or define a port other than 608 for RSCS to listen on.

    Managing UFT Links

    The host name a file will be delivered to can be specified using either dotted decimal or fully-qualified notation. If fully-qualified notation is desired, then the RSCSDNS user ID is required. See "Domain Name Server Support" for information on the RSCSDNS user ID.

    The TCPIP DATA file must contain these uncommented UFTserverID statements. These two entries enable you to send the files asynchronously using the RSCS UFT client and receive them using either the RSCS or TCP/IP UFTD servers.

    Statement Description
    UFTserverID RSCS Specifies the user ID the SENDFILE command will spool files to when using the UFTASYNC option. The default of * can be used as long as RSCS is specified in the SYSTEM NETID file.

    In addition, this statement is used by the PEEK and RECEIVE commands when receiving UFT files to indicate the local RSCS UFTD server user ID.

    UFTserverID UFTD Used by the PEEK and RECEIVE commands when receiving UFT files to indicate the local TCP/IP UFTD server user ID.

    Important Notes!
    • The CMS SENDFILE command included with VM/ESA 2.3.0, 2.4.0, or z/VM has a UFTASYNC option for preparing and sending files on an RSCS UFT-type link. See the full SENDFILE command description for options available with UFTASYNC.
    • Use caution when sending a file which has had keywords added manually to the beginning of a file. If you intend to use the CMS PRINT command, you will need to use the (CC option. Otherwise the RSCS UFT-type link will not find the keywords as the first data records of the spool file.
    • Any files already in NETDATA format should be sent using the CMS PUNCH command instead of using the CMS PRINT command.
    • The following information describes the file format required by the &PGMNAME. UFT support if the SENDFILE command is not sufficient.

    End users desiring to send files to remote users via UFT need to tag and spool (or other platform specific commands) their file to the RSCS UFT-type link. RSCS accepts files from locally connected users as well as remote users via any valid RSCS connection (NJE, RJE, LPD, etc.). The files must be in NETDATA format. Preceding any data records must be NETDATA control records containing file characteristics (format, record length, name, etc.). In addition, the following informational records must precede any NETDATA records for the UFT-type link to obtain and process:

    DESTADDR=userid@hostname
    Indicates the remote host and user ID the file is to be delivered to. A host name in either dotted decimal or fully-qualified notation is supported.
    TRANSLATE=string
    Provides 512-characters that RSCS will pack into a translate table to be used if translation to ASCII is required.
    TRANSFORM=type
    Used when forming the TYPE UFT command. The following types are supported:
    ASCII
    Data is to be translated to ASCII and a X'0D0A' is added to the end of each record.
    EBCDIC
    Data is sent without translation and a X'15' is added to th end of each record.
    BINARY
    Data is sent as a stream of data without translating.
    MAIL
    Data is sent as a stream of data after translating to ASCII.
    NETDATA
    Data is sent as contained when punched to RSCS without translating.
    VARREC
    Data is sent as variable record length with a two-byte length preceding each record of the data. The maximum supported logical record length when using this type is 65535.
    SPOOL
    For use when transferring a VM/ESA print or punch file between an RSCS UFT client and RSCS UFT server. The maximum supported logical record length for print files is 1280.

    Notes:

    1. The use of SPOOl is the only time the data is not required to be in NETDATA format.
    2. The DESTADDR=, and TRANSFORM= are required by the UFT-type link. If they are not found, message DMT265E will be issued and the file will be rejected and purged.

    UFT-Type Link use of Forms and Class

    The UFT-type link driver will support the use of forms and class under these conditions:

    • Class can be defined to restrict files processed by a UFT-type link
    • The LPRXFORM exit can be utilized to define a host name or translation table, if not provided within a keyword.

    If class processing is not desired, then class * must be used when defining or starting a UFT-type link. Otherwise, RSCS may not select files for processing by a UFT- type link.


    Parm Statement for a UFT-Type Link

    Format

     
                                                 +-DNSPort=900----+
                                                 |                |
         >>--PARM--linkid----+----------------+--+----------------+--+-----------------+-->
                             |                |  |                |  |                 |
                             +--DAYshold=nnn--+  +-DNSPort=portid-+  +--EParm='value'--+
         
     
                       +-FILehold=No--+  +-ITO=100-+  +-POrt=608----+  +-SIze=0---+
                       |              |  |         |  |             |  |          |
         >--EXIT=name--+--------------+--+---------+--+-------------+--+----------+-->
                       |              |  |         |  |             |  |          |
                       +-FILehold=Yes-+  +-ITO=nnn-+  +-POrt=portid-+  +-SIze=nnn-+
         
     
            +-SYStem=No--+  +-TCPid=TCPIP-+  +-TImeout=0---+
            |            |  |             |  |             |
         >--+------------+--+-------------+--+-------------+--><
            |            |  |             |  |             |
            +-SYStem=Yes-+  +-TCPid=tcpip-+  +-TImeout=nnn-+
    

    Note:

    (1) After linkid is specified, operands can be entered in any order, separated by blanks.

    Parameters

    linkid
    Is the one- to eight-character name of an UFT link that connects your local RSCS system to a remote UFT daemon. Before you can specify a PARM statement for a link, you must specify a LINKDEFINE (or LINK) statement with the same link ID.
    DAYshold=nnn
    Specifies the number of days, 0 to 365, undeliverable files will be placed on hold before requeueing it to a notify link. In order to requeue files to a notify link, a route for *UFTH* must be defined, for example:
    ROUTE *UFTH* TO *UFTHOLD
    
    This parameter must be used with an events file entry which periodically changes any files on hold to nohold for the UFT link. If a DAYshold parameter is not specified, the UFT link will continue indefinitely to try to deliver the file. If 0 is specified, the UFT link will requeue files to a notify link every time it places them on hold.
    DNSPort=900
    DNSPort=portid
    Specifies the port number on the local system which is running the RSCS Domain Name Server. The default is 900 if not specified.
    EParm='value'
    Specifies the exit routine parameter value associated with the exit routine name defined by EXIT. This parameter is a character string up to 239 bytes in length enclosed in single quotes (' '). Any character is allowed between the single quotes except another single quote ('). The actual value of the character string is defined by the specified exit routine.
    EXIT=name
    Specifies the one- to eight-character name of the exit module containing the five to six exit routines supporting the specific UFT driver. The exit module must exist in a LOADLIB that has been previously identified by use of the GCS GLOBAL command. If this keyword is omitted or if the exit module cannot be found, the line driver will not start.
    FILehold=No
    FILehold=Yes
    Specifies whether to place a file on hold when unable to connect to a remote UFT daemon after approximately 1 minute. The default is No which indicates the UFT link will continue connect attempts until successful or the link is STOPped.

    If defined as Yes, the UFT link will attempt to connect to the remote daemon at 1, 2, 4, 8, 16, and 32 second intervals. If still unable to connect, the file will be placed on hold. The RSCS events file can be used to periodically change any files with a status of HOLD to NOHOLD allowing for another delivery attempt. A sample RSCS events file entry which will change all held files to NOHOLD for an UFT-type link with linkname of UFT every 10 minutes would look like:

         *      M:010     *         *      *   CHANGE UFT HOLD NOHOLD
    
    ITO=100
    ITO=nnn
    Is a number from 0 to 100 that specifies the Inactivity Time Out value. The ITO value defines the length of time that can occur with no activity (that is, no file transmission or reception) before the link is deactivated. If this parameter is not specified, there is no inactivity time out for this link.

    If a link is ended because its ITO value has been exceeded, its restart exec will not be processed.

    The following values are permitted:

    0
    If specified, the link will be deactivated when there is no activity on the link. RSCS will first send files that are queued for transmission, or finish reception of the file currently being received, before deactivating the link.
    1-99
    Approximates the number of minutes until the link will be deactivated if there has been no activity on it.
    100
    If specified, there will be no ITO in effect. That is, the link will stay active until it is deactivated manually or until an unrecoverable error occurs.
    POrt=608
    POrt=portid
    Specifies the port number on the remote host to connect to. The default is port 608 if not specified. May be overridden on a file by file basis by the exit routines.
    SIze=nnn
    Specifies the maximum number of records the spool file may contain in order to be processed. The default is 0 which indicates no limit. If the number of records exceeds the maximum allowed amount, an error message will be issued to the user and console, and the file will be placed on hold. nnn can be between 0 (no limit) and 1048576 records.
    SYStem=No
    SYStem=Yes
    Specifies whether to search for a FORM table provided by the LPRXFORM exit using the FORM the file was spooled with. The default is No. The FORM table provides keywords which define the remote host name or IP address, translate table to use, and substitute form to use on the spool file, when sending the file to a remote UFT daemon, overriding the values defined for the link.
    TCPid=TCPIP
    TCPid=tcpip
    Specifies the name of the TCPIP virtual machine; defaults to TCPIP if not specified.
    TImeout=0
    TImeout=nnn
    Specifies the maximum amount of time, in seconds, to wait for a response from the remote daemon before aborting delivery of the file and placing it on hold. The default is zero indicating to wait indefinitely for a response from the remote daemon. nnn can be between 0 (wait indefinitely) and 2147483647 seconds.

    Parm Statement for a UFTD-Type Link

    Format

     
                                                             +-POrt=608----+
                                                             |             |
         >>--PARM--linkid----EXIT=name--+-----------------+--+-------------+-->
                                        |                 |  |             |
                                        +--EParm='value'--+  +-POrt=portid-+
         
     
            +-TCPid=TCPIP-+  +-Timeout=60--+
            |             |  |             |
         >--+-------------+--+-------------+--><
            |             |  |             |
            +-TCPid=tcpip-+  +-Timeout=nnn-+
    

    Note:

    (1) After linkid is specified, operands can be entered in any order, separated by blanks.

    Parameters

    linkid
    Is the one- to eight-character name of an UFTD driver that will act as a gateway accepting files from a UFT client within the TCP/IP environment into your RSCS network. Before you can specify a PARM statement for a link, you must specify a LINKDEFINE (or LINK) statement with the same link ID.
    EXIT=name
    Specifies the one- to eight-character name of the exit module containing the five to six exit routines supporting this UFTD link driver. The exit module must exist in a LOADLIB that has been previously identified on the GCS GLOBAL command. If this keyword is omitted or if the exit module cannot be found, the link driver will not start.
    EParm='value'
    Specifies the exit routine parameter value associated with the exit routine name defined by EXIT. This parameter is a character string up to 239 bytes in length and enclosed in single quotation marks (' '). Any character, except another single quotation mark ('), is allowed between the single quotation marks. The specified exit routine defines the actual value of the character string. The data between the quotation marks cannot be continued to the next line in a RSCS configuration file.
    POrt=608
    POrt=portid
    Specifies the port number on the local host to listen on. The default is port 608.
    TCPid=TCPIP
    TCPid=tcpip
    Specifies the name of the TCPIP virtual machine; the default name is TCPIP.
    Timeout=nnn
    Specifies the amount of time in seconds RSCS will wait for data when receiving from a TCP/IP UFT client prior to breaking the socket connection; the default is 60. nnn can be between 0 (wait indefinitely) and 2147483647 seconds. After the UFTD link driver breaks this connection, it will remain operational waiting for another UFT client to connect.


    Start Command Parameters for a UFT-Type Link

    Format

     
         >>--STArt--linkid--+---------------+--+-----------------------------+--><
                            +--TYPE UFT(1)--+  |                             |
                                               +--+-OParm---+--| Operands |--+
                                                  |         |
                                                  +-Parm(2)-+
         

    Operands:

     
                                +-DNSPort=900----+
                                |                |
         |--+----------------+--+----------------+--+-----------------+--+----------------+-->
            |                |  |                |  |                 |  |                |
            +--DAYshold=nnn--+  +-DNSPort=portid-+  +--EParm='value'--+  +--EXIT=name(1)--+
         
     
            +-FILehold=No--+  +-ITO=100-+  +-POrt=608----+  +-SIze=0---+
            |              |  |         |  |             |  |          |
         >--+--------------+--+---------+--+-------------+--+----------+-->
            |              |  |         |  |             |  |          |
            +-FILehold=Yes-+  +-ITO=nnn-+  +-POrt=portid-+  +-SIze=nnn-+
         
     
            +-SYStem=No--+  +-TCPid=TCPIP-+  +-TImeout=0---+
            |            |  |             |  |             |
         >--+------------+--+-------------+--+-------------+--|
            |            |  |             |  |             |
            +-SYStem=Yes-+  +-TCPid=tcpip-+  +-TImeout=nnn-+
    

    Note:

    (1) If field was not previously defined for the link, this field must be specified.
    (2) After PARM or OPARM is specified, operands can be entered in any order, separated from each other by blanks.

    Parameters

    linkid
    Is the one- to eight-character name of an UFT link that connects your local RSCS system to a remote UFT daemon.
    TYPE UFT
    Gives the name of the link-type. This specification overrides the link-type that may have been previously defined for the link. If no type was previously defined for the link, this field must be specified.
    OParm
    Parm
    Is a keyword signifying that one or more operation parameters follow.

    Operation parameters supplied after the OPARM operand override the corresponding parameters previously defined by a PARM configuration file control statement or a previous DEFINE command.

    Operation parameters supplied after the PARM operand override all parameters previously defined by a PARM configuration file control statement or a previous DEFINE command. That is, if no information is supplied after the PARM operand, all previously defined parameters are effectively negated. Any parameters not specified will assume the default values shown below.

    DAYshold=nnn
    Specifies the number of days, 0 to 365, undeliverable files will be placed on hold before requeueing it to a notify link. In order to requeue files to a notify link, a route for *UFTH* must be defined, for example:
    ROUTE *UFTH* TO *UFTHOLD
    
    This parameter must be used with an events file entry which periodically changes any files on hold to nohold for the UFT link. If a DAYshold parameter is not specified, the UFT link will continue indefinitely to try to deliver the file. If 0 is specified, the UFT link will requeue files to a notify link every time it places them on hold.
    DNSPort=900
    DNSPort=portid
    Specifies the port number on the local system which is running the RSCS Domain Name Server. The default is 900 if not specified.
    EParm='value'
    Specifies the exit routine parameter value associated with the exit routine name defined by EXIT. This parameter is a character string up to 239 bytes in length enclosed in single quotes (' '). All characters are allowed between the single quotes except another single quote ('). The actual value of the character string is defined by the specified exit routine.
    EXIT=name
    Specifies the one- to eight-character name of the exit module containing the five to six exit routines supporting the specific UFT driver. The exit module must exist in a LOADLIB that has been previously identified by use of the GCS GLOBAL command. If this keyword is omitted or if the exit module cannot be found, the line driver will not start. This specification overrides the exit name that may have been previously defined for the link. If no exit name was previously defined for the link, this field must be specified.
    FILehold=No
    FILehold=Yes
    Specifies whether to place a file on hold when unable to connect to a remote UFT daemon after approximately 1 minute. The default is No which indicates the UFT link will continue connect attempts until successful or the link is STOPped.

    If defined as Yes, the UFT link will attempt to connect to the remote daemon at 1, 2, 4, 8, 16, and 32 second intervals. If still unable to connect, the file will be placed on hold. The RSCS events file can be used to periodically change any files with a status of HOLD to NOHOLD allowing for another delivery attempt. A sample RSCS events file entry which will change all held files to NOHOLD for an UFT-type link with linkname of UFT every 10 minutes would look like:

         *      M:010     *         *      *   CHANGE UFT HOLD NOHOLD
    
    ITO=100
    ITO=nnn
    Is a number from 0 to 100 that specifies the Inactivity Time Out value. The ITO value defines the length of time that can occur with no activity (that is, no file transmission or reception) before the link is deactivated. If this parameter is not specified, there is no inactivity time out for this link.

    If a link is ended because its ITO value has been exceeded, its restart exec will not be processed.

    The following values are permitted:

    0
    If specified, the link will be deactivated when there is no activity on the link. RSCS will first send files that are queued for transmission, or finish reception of the file currently being received, before deactivating the link.
    1-99
    Approximates the number of minutes until the link will be deactivated if there has been no activity on it.
    100
    If specified, there will be no ITO in effect. That is, the link will stay active until it is deactivated manually or until an unrecoverable error occurs.
    POrt=608
    POrt=portid
    Specifies the port number on the remote host to connect to. The default is port 608 if not specified. May be overridden on a file by file basis by the exit routines.
    SIze=nnn
    Specifies the maximum number of records the spool file may contain in order to be processed. The default is 0 which indicates no limit. If the number of records exceeds the maximum allowed amount, an error message will be issued to the user and console, and the file will be placed on hold. nnn can be between 0 (no limit) and 1048576 records.
    SYStem=No
    SYStem=Yes
    Specifies whether to search for a FORM table provided by the LPRXFORM exit using the FORM the file was spooled with; the default is No. The FORM table provides keywords which define the remote host name or IP address, translate table to use, and substitute form to use on the spool file, when sending the file to a remote UFT daemon, overriding the values defined for the link.
    TCPid=TCPIP
    TCPid=tcpip
    Specifies the name of the TCPIP virtual machine; defaults to TCPIP if not specified.
    TImeout=0
    TImeout=nnn
    Specifies the maximum amount of time, in seconds, to wait for a response from the remote daemon before aborting delivery of the file and placing it on hold. The default is zero indicating to wait indefinitely for a response from the remote daemon. nnn can be between 0 (wait indefinitely) and 2147483647 seconds.

    Usage

    1. RSCS will truncate any command received via the CP SMSG facility or the RSCS console at 132 bytes. This may limit the amount of EPARM data which can be passed on the START command.
    2. CP converts all data that is entered from the RSCS console or sent using the CP SMSG command to uppercase letters. To ensure the correct letters are used in any EPARM data, you can create an exec using:
      'EXECIO * CP (STEM CPMSG. STRING SMSG serverid options'
      

      Where:

      serverid
      Specifies the CP name of the RSCS virtual machine.
      options
      Specifies the uppercase RSCS command and any options which may need to be in mixed case.

    Start Command Parameters for a UFTD-Type Link

    Format

     
         >>--STArt--linkid--+----------------+--+-----------------------------+--><
                            +--TYPE UFTD(1)--+  |                             |
                                                +--+-OParm---+--| Operands |--+
                                                   |         |
                                                   +-Parm(2)-+
         

    Operands:

     
                                                     +-POrt=608----+  +-TCPid=TCPIP-+
                                                     |             |  |             |
         |--+-----------------+--+----------------+--+-------------+--+-------------+-->
            |                 |  |                |  |             |  |             |
            +--EParm='value'--+  +--EXIT=name(1)--+  +-POrt=portid-+  +-TCPid=tcpip-+
         
     
            +-Timeout=60--+
            |             |
         >--+-------------+--|
            |             |
            +-Timeout=nnn-+
    

    Note:

    (1) If field was not previously defined for the link, this field must be specified.
    (2) After PARM or OPARM is specified, operands can be entered in any order, separated from each other by blanks.

    Parameters

    linkid
    Is the one- to eight-character name of an UFTD driver that will act as a gateway accepting files from a UFT client within the TCP/IP environment into your RSCS network.
    TYPE UFTD
    Gives the name of the link-type. This specification overrides the link-type that may have been previously defined for the link. If no type was previously defined for the link, this field must be specified.
    OParm
    Parm
    Is a keyword signifying that one or more operation parameters follow.

    Operation parameters supplied after the OPARM operand override the corresponding parameters previously defined by a PARM configuration file control statement or a previous DEFINE command.

    Operation parameters supplied after the PARM operand override all parameters previously defined by a PARM configuration file control statement or a previous DEFINE command. That is, if no information is supplied after the PARM operand, all previously defined parameters are effectively negated. Any parameters not specified will assume the default values shown below.

    EParm='value'
    Specifies the exit routine parameter value associated with the exit routine name defined by EXIT. This parameter is a character string up to 239 bytes in length and enclosed in single quotation marks (' '). Any character, except another single quotation mark ('), is allowed between the single quotation marks. The specified exit routine defines the actual value of the character string.
    EXIT=name
    Specifies the one- to eight-character name of the exit module containing the five to six exit routines supporting the specific UFTD driver. The exit module must exist in a LOADLIB that has been previously identified by use of the GCS GLOBAL command. If this keyword is omitted or if the exit module cannot be found, the link driver will not start. This specification overrides the exit name that may have been previously defined for the link. If no exit name was previously defined for the link, this field must be specified.
    POrt=608
    POrt=portid
    Specifies the port number on the local host to listen on. The default is port 608.
    TCPid=TCPIP
    TCPid=tcpip
    Specifies the name of the TCPIP virtual machine; the default name is TCPIP.
    Timeout=nnn
    Specifies the amount of time in seconds RSCS will wait for data when receiving from a TCP/IP UFT client prior to breaking the socket connection; the default is 60. nnn can be between 0 (wait indefinitely) and 2147483647 seconds. After the UFTD link driver breaks this connection, it will remain operational waiting for another UFT client to connect.

    Usage

    1. RSCS will truncate any command received via the CP SMSG facility or the RSCS console at 132 bytes. This may limit the amount of EPARM data which can be passed on the START command.
    2. CP converts all data that is entered from the RSCS console or sent using the CP SMSG command to uppercase letters. To ensure the correct letters are used in any EPARM data, you can create an exec using:
      'EXECIO * CP (STEM CPMSG. STRING SMSG serverid options'
      

      Where:

      serverid
      Specifies the CP name of the RSCS virtual machine.
      options
      Specifies the uppercase RSCS command and any options which may need to be in mixed case.


    UFTXOUT Routine

    UFTXOUT sample exit routine performs functions to support transmitting one file to a remote UFT daemon at a time. Multiple UFT link drivers can be defined using this sample exit. It also performs simple translation of data to ASCII.

    The UFT commands created by UFTXOUT are the minimum necessary for transmitting the data, these include:

    • CLASS
      From the tag (TAGCLASS). In addition, if the transform is SPOOL, the spool file device type will be appended to TAGCLASS as PUN, 1403, 3211, 3800, or VAFP. Print files with a logical record length equal to or less than 1280 are supported.
    • COPY
      From the tag (TAGCOPY).
    • DATE
      The date, time, and time zone of the file from the UFTBLOK (as specified by an INMR02 NETDATA control record) or if not specified, from the tag (TAGINTOD).
    • DEST
      From the tag (TAGDEST), if specified.
    • DIST
      From the tag (TAGDIST), if specified.
    • EOF
    • FILE
      This only needs to be an estimated size. The value specified in the UFTBLOK (from an INMR02 NETDATA control record) will be used if specified; otherwise zero is used.
      In addition, the second required parameter will be the originator of the file (TAGINVM).
    • FORM
      From the tag (TAGFORMN) , if specified.
    • NAME
      This will be in the form 'file name.file type'. From the UFTBLOK (as specified by an INMR02 NETDATA control record).
    • OWNER
      From the OWNER= record of the configuration file, if specified.
    • RECFMT
      From the UFTBLOK (as specified by an INMR02 NETDATA control record).
    • RECLEN
      From the UFTBLOK (as specified by an INMR02 NETDATA control record).
    • TYPE
      This will be determined from the transform field of the UFTBLOK. UFTXOUT will support these transform types:
      Type Code Description
      ASCII A Data will be translated, X'0D0A' added to end of each record.
      BINARY I File data will be transmitted unaltered.
      EBCDIC E X'15' added to end of each record.
      MAIL M Data will be translated to ASCII.
      NETDATA N File transmitted in NETDATA format.
      SPOOL V M Two-byte length followed by CCW opcode will precede each data record. This allows VM spool files to be transferred to another VM system unaltered.
      TEXT A Data will be translated, X'0D0A' added to end of each record.
      VARREC V Two-byte length will precede each data record.

      Note: VARREC doesn't support a logical record length greater than 65535.

      Note: Any other type received will be rejected.
    • USER
      This will be as parsed from the data prior to the at sign (@) character in the DESTADDR= keyword.

    When using the UFTXOUT routine, you can also specify the following EPARM values on the PARM statement for the UFT-type link.

    Note: The EPARM parameter is limited to 239 bytes of data; these options may be useful for small amounts of data only.

    Config=ddname
    Specifies the ddname which has been defined as an exit configuration file. If the ddname does not exist, the UFTXOUT initialization exit routine will pass back a return code to cause the UFT-type link to issue an error message and drain. If this exit parameter is not used, a configuration file is not read by the UFTXOUT exit causing existing defaults to be used for values which can be defined by the configuration file. This configuration file is used to supply the following:
    • Translation tables to override the ones used by the exit.
    • Overrides for the UFT commands created by UFTXOUT.

    The configuration file can have any desired filename and filetype and must be on a disk accessed by the RSCS user ID. This file must be defined with a FILEDEF statement in the PROFILE GCS. The DDNAME used must be supplied on the Config= link exit parameter statement when defining the UFT-type link in the RSCS CONFIG file.

    A sample PROFILE GCS DDNAME entry:

    'FILEDEF UFTOUT DISK UFTO SCONFIG *'
    
    Where UFTOUT is the DDNAME defined and UFTO SCONFIG is the name of the configuration file.

    A sample RSCS CONFIG parameter (PARM) for an UFT-type link with linkname UFT using the DDNAME defined on the FILEDEF statement in the PROFILE GCS:

    PARM UFT EXIT=UFTXOUT EPARM='C=UFTOUT'
    

    The UFTXOUT configuration file has the following layout:

    • An * in column one denotes a comment line. Any line that does not have an * in column one will be interpreted as a configuration entry. All entries must be capitalized.
    • Entries can span multiple records.

    The following configuration records are supported:

    OWNERNAME=string
    Used to specify an owning user ID name, up to 32 characters, for the OWNER UFT command.
    TOASCII=string
    Provide a table for EBCDIC to ASCII translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCII= records to replace the 256-byte translation table.
    TOASCIIC=string
    Provide a table for EBCDIC to ASCII translation of UFT commands, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCIIC= records to replace the 256-byte translation table.

    UFTXIN Routine

    The UFTXIN sample exit routine performs functions to support a single UFTD connect request. Multiple UFTD link drivers can be defined using this sample exit. It also performs simple translation of data to EBCDIC.

    Note
    The UFTXIN sample UFTD link driver exit will operate more consistently and seamlessly if UFT commands are sent prior to the data. UFTXIN will however accept UFT commands second. However, information required for file processing may not be setup as desired.

    The UFTXIN routine parses the user name on the USER command received from the UFT client in the form userid<@nodeid> or userid<%nodeid> as follows:

    KERRY
    Will set the node ID to the local node name and the user ID to KERRY. The file will be spooled to user KERRY on the local system.
    KERRY@
    Will set the node ID to the local node name and the user ID to KERRY. The file will be spooled to user KERRY on the local system.
    KERRY%
    Will set the node ID to the local node name and the user ID to KERRY. The file will be spooled to user KERRY on the local system.
    KERRY@GDLVM7
    Will set the node ID to GDLVM7 and the user ID to KERRY causing the file to be sent to user KERRY at node GDLVM7.
    KERRY%GDLVM7
    Will set the node ID to GDLVM7 and the user ID to KERRY causing the file to be sent to user KERRY at node GDLVM7.
    @LASER3
    Will set the node ID to LASER3 and the user ID to SYSTEM causing the file to be sent to the network node LASER3.
    %LASER2
    Will set the node ID to LASER2 and the user ID to SYSTEM causing the file to be sent to the network node LASER2.
    anything_else
    Will search for a username entry specified within the UFTXIN configuration for options on handling the file.

    Note: The UFTXIN routine will limit the length of the userid and nodeid fields to eight characters. Any extra data in those operand fields will be discarded. In addition, only 32 characters of the USER command data will be used.

    UFT commands supported by this exit are:

    • ABORT
      Cause the spool file to be closed and purged.
    • CLASS
      First character of the first operand of the data will be used for the class field of the tag (TAGCLASS). The second operand, if specified when TYPE is "V M" (operand is ignored for all other TYPE's), will indicate the file was from VM spool and whether it was a PRT or PUN device.
    • COPY
      Will be used for the copy count field of the tag (TAGCOPY).
    • DATe
      Will be used to create the file origin TOD value in the tag (TAGINTOD).
    • DESTination
      First eight characters of the data will be used for the destination field of the tag (TAGDEST).
    • DISTribution
      First eight characters of the data will be used for the distribution field of the tag (TAGDIST).
    • EOF
      Cause the spool file to be closed and delivered.
    • FILE
      First eight characters of the from data will be used for the origin user field of the tag (TAGINVM).
    • FORM
      First eight characters of the data will be used for the form field of the tag (TAGFORMN).
    • NAME
      The first eight characters of the file name and the first eight characters of the file extention will be used for the dataset name field of the tag (TAGDSN). Some parsing will be done to remove dots and slashes. For example:
      C:\WINDOWS\SYSTEM\AUTOEXEC1234.BAT
      
      will become AUTOEXEC BAT
    • OWNER
      First eight characters of the data will be used for the origin user field of the tag (TAGINVM) overriding the information supplied on the FILE UFT command if provided.
    • RECFMT
      Used when creating the INMR2 control record.
    • RECLen
      Defines the maximum allowed line width. This will become TAG field TAGRECLN.
    • TITLE
      Will be used for the title line on each page if pagination was requested in the matching username (or DEFAULT) record defined within the UFTXIN configuration file.
    • TYPE
      Will be used to determine whether or not to translate data into EBCDIC and how to spool the data.
    • USER
      First 17 characters of the data will be used for the destination user field of the tag (TAGTOVM) and the destination node field of the tag (TAGTOLOC).
      In addition, the first 32 characters of the data will be used to search for a matching username within the UFTXIN configuration file.

    In addition, the UFTXIN routine supports comment records * and #.

    When using the UFTXIN routine, you can also specify the following EPARM values on the PARM statement for the UFT-type link.

    Note: The EPARM parameter is limited to 239 bytes of data; these options may be useful for small amounts of data only.

    Config=ddname
    Specifies the ddname which has been defined as an exit configuration file. If the ddname does not exist, the UFTXIN initialization exit routine will pass back a return code to cause the UFTD-type link to issue an error message and drain. If this exit parameter is not used, a configuration file is not read by the UFTXIN exit causing existing defaults to be used for values which can be defined by the configuration file.

    The UFTXIN sample exit routine configuration file can be used to supply the following:

    • Overrides for processing when a file is received from a remote UFT client based on the user name.
    • A translate table to override the one used by the exit.
    • Override the host name used in the herald response message.
    • Provide a domain name used in the herald response message.

    The configuration file can have any desired filename and filetype and must be on a disk accessed by the RSCS user ID. This file must be defined with a FILEDEF statement in the PROFILE GCS.

    A sample PROFILE GCS DDNAME entry:

    'FILEDEF UFTIN DISK UFTI SCONFIG *'
    
    Where UFTIN is the DDNAME defined and UFTI SCONFIG is the name of the UFTXIN configuration file.

    A sample RSCS CONFIG parameter (PARM) for an UFTD-type link with linkname UFTD using the DDNAME defined on the FILEDEF statement in the PROFILE GCS:

    PARM UFTD EXIT=UFTXIN EPARM='C=UFTIN'
    

    The UFTXIN configuration file has the following layout:

    • An * in column one denotes a comment line. Any line that does not have an * in column one will be interpreted as a configuration entry. All entires must be capitalized.
    • Entries can span multiple records.

    The following configuration records are supported:

    DOMAINAME=string
    Used to specify a domain name, up to 255 characters, to be appended after the host name of the positive herald response message (message sent in response to a connect request from a remote UFT client). A period (.) will be inserted between the host name and domain name. This record can be used to add a domain name after the host name, which by default is the local RSCS node name.
    HOSTNAME=string
    Used to specify a host name, up to 255 characters, used within the positive herald response message (message sent in response to a connect request from a remote UFT client) overriding the default, which is the the local RSCS node name.
    TOASCII=string
    Provide a table for EBCDIC to ASCII translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOASCII= records to replace the 256-byte translation table.
    TOEBCCMD=string
    Provide a table for ASCII to EBCDIC translation of the UFT commands, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOEBCCMD= records to replace the 256-byte translation table.
    TOEBCDIC=string
    Provide a table for ASCII to EBCDIC translation, overriding the default used by the exit. Up to 512 hexadecimal (0-9, A-F) characters may be specified on multiple TOEBCDIC= records to replace the 256-byte translation table.
    username
    Provide the ability to override defaults used by UFTXIN on a user name basis when receiving a file from a remote UFT client. Multiple, unique, username records can be specified. The layout of the username records are as follows:
    • Each username option is separated by one or more blanks.
    • The parameters are not column dependent.
    • One record per line, continuation is not supported.
    • Each parameter IS position dependent
    • An * can be used in a position (other than for the user name) to tell UFTXIN to use the existing default.
    • The user name will be parsed into user ID and node ID as follows:
      userid<@nodeid>
      userid<%nodeid>
      userid
      node ID will be set to local node name.
      @nodeid
      user ID will be set to SYSTEM.
      %nodeid
      user ID will be set to SYSTEM.
      userid@
      node ID will be set to local node name.
      userid%
      node ID will be set to local node name.
      NONEOFTHEABOVE
      node ID and user ID MUST be set within record.
      The userid and nodeid parsed from the user name can be overridden within the record. If both are overridden, the user name is not parsed. If neither one is overridden, the user name is parsed into user ID and node ID which must be valid (either of which can still be overridden within).
    The format of the username records are:
    username ppos lpage class forms jobn dest pagination userid nodeid tcpxlbin netdata
    DEFAULT ppos lpage class forms jobn dest pagination userid nodeid tcpxlbin netdata
    
    username
    is a user name up to 32 characters. A username of DEFAULT can be used to define parameters for any user name not defined by a configuration file record. When a user name arrives, UFTXIN first looks for a configuration record of that name; if not found it will look for a configuration record using DEFAULT; if not found it will use existing UFTXIN defaults unless otherwise noted.
    ppos
    is the logical record length 1-65535 when the file will be spooled in NETDATA format, otherwise 1-32760; default is 255 if the RECLen UFT command is not received.
    lpage
    is the number of lines per page 1-99; default is 66. This parameter is only valid if the pagination parameter has been set to PAGE.
    class
    is the one character spool file class; default is blank if the the CLASS UFT command is not received.
    forms
    is the one- to eight-character spool file form; default is blank if the the FORM UFT command is not received.
    jobn
    is the one- to eight-character job name; default is SYSTEM.
    dest
    is the one- to eight-character PSF destination; default is blank if the the DESTination UFT command is not received. When using a PSF destination, UFTXIN will set the user ID field of the tag to SYSTEM.
    When using a PSF destination, the user name can be in the form SYSTEM@nodeid. Alternatively, the user name can be anything unique as long as the user ID field is SYSTEM or * and node ID field is specified.
    pagination
    is either PAGE or NOPAGE; default is NOPAGE. This parameter determines how pagination will be performed as follows:
    • PAGE will cause UFTXIN to paginate.
    • NOPAGE will cause UFTXIN not to paginate.
    userid
    is the one- to eight-character user ID the file should be spooled to; default is derived from the user name.

    Note: If a PSF destination is provided by dest, then the userid field can only be set to SYSTEM.

    nodeid
    is the one- to eight-character destination node ID the file should be spooled to; default is derived from the user name.
    tcpxlbin
    is the filename of a TCP/IP tcpxlbin translate table to be used for this user name. The file must exist on any accessed disk. If not specified, the translation table used will either be the default one within UFTXIN or the override specified within the UFTXIN configuration file.
    netdata
    is either YES, or NO; the default is YES. Netdata specifies whether the data should be spooled in NETDATA format as follows:
    YES
    Spool data in NETDATA format.
    NO
    Spool data as plain records, not in NETDATA format. This is the desired format if the destination of the file is a printer.

    Note: This does not apply if the UFT type is NETDATA.

    Examples of Username

    This example would allow a file to be received without translating, and spooled to an LPR link using the LPRXONE exits causing the file to be sent unaltered to a remote LPR daemon:

    LPR@NODEONE 1280 50 * STDN * * * ASCII * * NO
    

    This example defines a username used to spool input to the system printer:

    LOCALNODE * * * * * SYSTEM * * * NO
    

    This example shows the defaults defined within UFTXIN.

    DEFAULT 255 66 * * SYSTEM * NOPAGE * * * YES