Listener Definitions (LD)

The Listener Definitions (LD) specify methods that a CICS® region uses to listen for connection requests that are coming from IBM® CICS Transaction Gateway products across TCP/IP or local SNA connections.

<Key>

This attribute specifies a 12-byte identifier for the LD entry. LD keys are not enabled for National Language Support (NLS). CICS allows the ASCII characters A through Z, 0 through 9, dollar ($), at sign (@), and number sign (#).

If you are using the IBM TXSeries Administration Console, SMIT (CICS for AIX), to set this value, see Restrictions on the use of characters.

ActivateOnStartup (Activate resource at cold start)

This attribute specifies whether a resource definition is always copied from the permanent database to the runtime database at the cold start of a region. If the attribute is set to yes, the resource definition is always copied from the permanent database to the runtime database. If the attribute is set to no, the resource definition is not copied to the runtime database unless its group has been specified in the Groups attribute of the Region Definitions (RD). The default value is yes.

AmendCounter (Number of updates)

This attribute is reserved for CICS internal use.

CICSUserId (CICS userid for IIOP)

This is the default user ID that is used for Internet Inter-ORB Protocol (IIOP) requests. It can be overridden by one of the IIOP user exits. This user must be defined to the CICS region. If the user is not defined or if this entry is null, the requests run under the default, CICSUSER. The default value is "".

GatewayCDSName

The name is specified in a 32-byte string. This attribute can take either the full pathname of the PPC Gateway server (for example, /.:/cics/ppc/gateway/CICSOPEN) or a partial name (for example, CICSOPEN). CICS prefixes a partial name with the string /.:/cics/ppc/gateway/. For example, if you specify the partial name CICSOPEN as the value for the GatewayCDSName attribute, CICS uses the full path /.:/cics/ppc/gateway/CICSOPEN. The default value is "".

GroupName (Group to which resource belongs)

This attribute specifies the name of a group to which this resource definition belongs. The name is specified in an eight-byte string. For cold starts, you can specify that CICS copies, from the permanent database to the runtime database, resource definitions that belong to groups that are named in the Groups attribute of the Region Definitions (RD). (This can be done in addition to setting the ActivateOnStartup attribute to yes for resources whose definitions are to be copied on startup from the permanent database to the runtime database.) The default value is "", which specifies no group.

NamedPipeName (local Named Pipe name) (CICS for Windows only)

This attribute specifies the entry in the file prodDir\bin\cicslcli.ini, which is used by the command cicslterm to connect to this region. The value of the attribute must be six alphanumeric characters, of which the last two characters must be unique within the local system. The default value is "".

Permanent (Protect resource from modification)

This attribute specifies whether amending or deleting the permanent database entry is permitted. If the attribute is set to no, the entry can be amended or deleted. If the attribute is set to yes, the entry cannot be modified or deleted. To modify the entry, reset the attribute to no and after amending the entry, set the attribute back to yes. The default value is no.

Protocol (Protocol type)

This attribute specifies the type of LD entry. If it is set to TCP, the LD entry is for CICS Transaction Gateway that are using TCP/IP and for CICS family TCP/IP connections. If it is set to SNA, the LD entry is for local SNA support. If it is set to IPIC, the LD entry is for CICS Transaction Gateway that are using TCP/IP with IPIC support and for IPIC over TCP/IP connections. If it is set to NamedPipe, the LD entry is for a cicslterm terminal. If it is set to LU0, the LD entry is for SNA LU0 communications (Windows only). If it is set to IIOP, the LD entry is for IIOP clients that are using TCP/IP IIOP connections. The default value is TCP.

ResourceDescription (Resource description)

This attribute specifies this LD entry with a 30-byte string. The default value is "Listener Definition".

SNAServerTransport

This attribute is not supported.

SNAServerIdentifier

This attribute is not supported.

SNAServerNodeName

This attribute is not supported.

SSLAuthentication (Level of SSL authentication required)

This attribute specifies whether SSL authentication is supported by an IPIC listener. The value no indicates that the listener does not support SSL. Other values are yes and client. Specify yes to configure an IPIC SSL listener that accepts SSL flows other than client authentication. Specify client to accept all SSL flows including client authentication. When client authentication is specified, client must send the certificate. The default value is no.

SSLCertificate (Server's certificate name in keyring file)

This attribute specifies the name (label) of the certificate for this SSL listener in the key database file. The default value is "", which causes CICS to use the default nominated certificate in the database.

SSLCipherspecs

This attribute specifies the TLS cipher specs to be used for encryption by an SSL-enabled IPIC listener. For more information, see Supported CipherSpecs.

The following list contains the string values that can be used with the buf_value for this buffer ID. Any combination of these can be used; none can be used twice.

• 00 - NULL NULL
• 01 - NULL MD5
• 02 - NULL SHA
• 03 - RC4 MD5 Export
• 04 - RC4 MD5 US
• 05 - RC4 SHA US
• 06 - RC2 MD5 Export
• 09 - DES SHA Export
• 62 - DES SHA Export1024
• 64 - RC4-56 SHA Export1024
• 0A - Triple DES SHA US
• 2F - TLS_RSA_WITH_AES_128_CBC_SHA
• 35 - TLS_RSA_WITH_AES_256_CBC_SHA

The 2F and 35 cipher specs are supported only for Windows and AIX-PPC systems. If a NULL string ("") is specified for the cipherspec list, SSL version 3 will not be used.

The default value is “05040A6264030609020100”.

SSLEncryption (Level of SSL encryption required)

This attribute specifies the level of encryption that is required on an SSL-enabled IIOP listener. Possible values are no, yes, and strong. Specify no for using SSL message integrity support (no encryption); specify yes or strong for SSL message encryption using 40-bit or 128-bit encryption keys, respectively. The default value is no.

Note: 128-bit keys might not be available in some countries.

SSLKeyFile (Fully qualified pathname of the SSL keyring file)

This attribute specifies the location and name of the SSL key database file. The default value is "".

SSLKeyPassword (Password of the SSL keyring file)

This attribute specifies the password for the SSL key database file. If no password is specified, CICS assumes that a password has been saved in a stash file in the directory that contains the SSL key database file. The default value is "".

SSLKeyPwdStashfile

This attribute specifies the fully qualified path name of the SSL keyring password stash file. The password stash file can be generated while setting the password for the newly created keyring file. When authenticating, the password stash file can be used instead of the password.

SSLSessionTimeout (SSL session key timeout value (mins))

This attribute specifies the period (in minutes) for SSL to time out the current session key. SSL then attempts to create a new session key. The default value is 0 (the timeout is 1 day).

TCPAddress (TCP adapter address)

This attribute defines which local network adapter addresses are used by CICS to accept TCP/IP connections. It is applicable only with the Protocol attribute set to TCP. Set the TCPAddress attribute to "" when connection requests are to be accepted on any of the network adapters that are configured on the local machine. Alternatively, set TCPAddress to a single network adapter address in one of the following forms:

• The Internet Protocol (IP) version 4 (IPv4) address in dotted decimal notation. For example, 1.23.45.67. Do not use leading zeros when specifying an address in dotted decimal notation. CICS interprets such an entry as octal.
• The IP address in dotted hexadecimal notation. For example, 0x01.0x17.0x2D.0x43.
• The Internet Protocol version 6 (IPv6) address in colon hexadecimal notation. For example, 2001:db8:3333:4444:5555:6666:7777:8888.
• The host name that is defined in the Internet name service. For example, aix5.cicsland.com.

The default value is "".

Note: Dotted hexadecimal notation is not supported for IPIC protocol (cics_ipic).

TCPIPFamily

This attribute specifies the type of TCP/IP family address to use for listening:

• If you have set it to ipv4, the listener will listen on IPv4 address.
• If you set it to ipv6, the listener will listen on IPv6 address.
• If it is set to any, the listener will first try to listen on IPv4 address. If it is not available then, it will try to listen on IPv6 address. Not both..
• If it is set to all, the listener will listen on both IPv4 and IPv6 addressing, subject to availability.

The default value is any. See Table 2.

TCPProcessCount (TCP process count)

This attribute is valid only for listener definitions that have the Protocol attribute set to TCP. It defines how many listener processes CICS will create to listen on the defined port and addresses. The default value is 1, and the range of values allowed is 1 through 512. Values that are greater than 1 cause CICS to autoinstall peer listener processes into the system during region startup. To do this, it uses an automated naming scheme SYS$CICSxxxx where xxxx is an alpha string starting from AAAA. These peer listeners cooperate to balance the number of connected client systems between themselves and the main listener process.

In configurations that have many client systems, this attribute can give simple configuration of the clients (they all use the same Internet address and port) and an efficient balance of resources within each listener process. This is desirable to avoid reaching operating system thread limits, file descriptor limits, and internal process contention for resources. The actual setting used should be determined with reference to workload profiles, but as a general rule, try to keep below 500 the average number of client systems that any single listener process handles. So, for example, if you require connections for a maximum of 2000 client machines, set this attribute to 5, to keep the average number of connections below 500.

The default value for listener definitions that have the Protocol attribute set to IPIC is 1. For listener definitions with Protocol type set to IPIC, if the value is set to greater than 1, it has no effect and still only one listener process is started.

TCPService (TCP service name)

This attribute specifies the service name in the file /etc/services (CICS on Open Systems) or %SystemRoot%\system32\drivers\etc\services (CICS for Windows). CICS uses this service name when starting the TCP protocol. A value of "" means the reserved CICS port number (1435/tcp) is used. The default value is "". This value can be left blank for listener definitions with the Protocol type set to IPIC

Entries in /etc/services (CICS on Open Systems) or %SystemRoot%\system32\drivers\etc\services (CICS for Windows) for the TCPService attribute must specify the port number and the TCP protocol. For example, if the TCPService attribute is set to cicstcp, the file /etc/services (CICS on Open Systems) or %SystemRoot%\system32\drivers\etc\services (CICS for Windows) can contain the following:

cicstcp       2345/tcp     # CICS Clients
cicsipc    2346/tcp  #IPIC support

TCP/IP Listener instances for TXSeries cannot use port numbers greater than 65535. If you configure your TCP/IP listener instances to listen for incoming communication requests on a port number that is greater than 65535, the instance will start successfully, but it will not be listening for incoming requests on that port number. For example, if you have txlistener 75000/tcp in your /etc/services file and TCPService=txlistener in LD.stanza, then the listener will listen on port 9464 (75000 - 65536 = 9464).

Note: If this value is the same as the number of one of the reserved ports of the operating system, an error will be displayed.