Communications Definitions (CD)

The Communications Definitions (CD) describe the configuration of other systems with which a CICS® region communicates, including other CICS family systems. Each CD entry describes a remote system. The communications can use TCP/IP or Systems Network Architecture (SNA). A region can communicate with the following remote systems:

Another CICS system
A PPC application
An SNA Logical Unit (LU) type 6.2 system

CD entries are also created dynamically (initialized automatically) when an IBM® CICS Transaction Gateway attaches to a region or when a CICS family TCP/IP or IPIC over TCP/IP connection is acquired. The Communications Definitions (CD) include the following attributes:

<Key>: Specifies the local name for a remote system with which the CICS region can communicate and is the key of the CD. This is referred to as the SYSID by application programs. This key is not affected by National Language Support (NLS). It can contain up to four characters from the set A through Z, the numerals 0 through 9, the dollar sign ($), and the at sign (@). For all the permanent database operations, and on a runtime database insert operation, CICS performs class-specific validation of the bytes that form the database key.
If you are using the IBM TXSeries Administration Console, SMIT (CICS for AIX), or SAM (CICS for HP-UX) to set this value, see Restrictions on the use of characters.

ActivateOnStartup (Activate the resource at cold start): 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.

AllocateTimeout (Timeout on allocate (in seconds))

Specifies how many seconds a front-end transaction waits for a back-end transaction to be started over a communications link. The default value is 60. This attribute is applicable only to PPC-based connections (where the ConnectionType attribute is set to ppc_tcp or ppc_gateway).

AmendCounter (Number of updates)

Reserved for CICS® internal use.

ConnectionType (Connection type)

Specifies the type of the connection to the remote system. The values local_sna and ppc_gateway are used for connections across SNA networks. The values cics_tcp, ppc_tcp, and cics_ipic are for connections that use TCP/IP. For more information about the types of connections that CICS supports, see Designing your network configuration. The default value is ppc_tcp.

DefaultSNAModeName (Default modename for an SNA connection)

Specifies the default modename for an SNA connection. If the ConnectionType attribute is set to local_sna or ppc_gateway, set this attribute to the name of the SNA mode group that most of your intersystem requests use. This means that when an intersystem request is made on this connection by a transaction that does not specify an SNA modename in either the PROFILE option of the EXEC CICS ALLOCATE command or the SNAModeName attribute of the Transactions Definition (TD) entry, CICS requests the modename that is specified by the DefaultSNAModeName attribute.

The default value of DefaultSNAModeName is "", meaning that the modename that is used depends on the configuration for your SNA product. For more information about configuring mode names, see Using default modenames.

This attribute is ignored if the ConnectionType attribute is set to cics_tcp or ppc_tcp.

GatewayName (Gateway Definition (GD) entry name)

Specifies the name of the Gateway Definitions (GD) entry that describes the PPC Gateway server that is to be used for this connection. GatewayName is required only if the ConnectionType attribute is set to ppc_gateway. The default value is "".

GroupName (Group to which resource belongs)

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 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.

InService (Set connection in service)

Specifies whether CICS allows intersystem requests to be sent to, or received from, the remote system. Set the attribute to no if communications with the remote system are not to be allowed initially. The connection can later be set in service by using EXEC CICS SET CONNECTION. The default value is yes.

LinkUserId (UserId for inbound requests)

Specifies a locally defined user ID that can be associated with inbound requests.

The following attributes are used in conjunction with the LinkUserId attribute:

The CD RemoteSysSecurity attribute
The RD DefaultUserId attribute, in addition to the TSL and RSL keys that are defined in the UD entry for the user ID that is specified with this attribute

If a value is not specified for the LinkUserId attribute, the CD TSLKeyMask and RSLKeyMask attributes are used to determine authorization.

Note: It is recommended that a UD entry is defined for the user ID that is specified with the LinkUserId attribute. For more information about how this attribute is used for intersystem requests, see Configuring intersystem security.

The default value is "".

ListenerName (Listener Definition (LD) entry name)

Specifies the name of an LD entry that has the Protocol attribute set to TCP. The Internet Protocol (IP) address and port number that are specified by this LD entry are used by the remote system to contact the local region. The ListenerName attribute is required only if the ConnectionType attribute is set to cics_tcp or local_sna, and in these cases it must be specified even if the connection is to be used only for outbound requests. The default value is "".

OutboundUserIds (Send userids on outbound requests)

Specifies whether user IDs are to be sent on outbound requests. It takes the following values:

sent: Specifies that user IDs are sent on outbound requests for this connection.
not_sent: Specifies that user IDs are not sent on outbound requests for this connection.
sent_only_with_pswd: Specifies that the user ID is sent with its password. If the password is not available, the user ID is not sent.
sent_maybe_with_pswd: Specifies that the user ID is sent with its password. If the password is not available, the user ID is sent “already-verified”.

The default value is sent.

Permanent (Protect resource from modification)

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, an entry cannot be modified or deleted. To change the entry, first reset the attribute to no. After amending the entry, set the attribute back to yes. The default value is no.

ReceiveCount: Specifies, in the range 1-999, the number of receive sessions; that is, sessions that receive incoming requests. The actual number of receive sessions that are used depends also on the number of send sessions defined in the remote system. When the connection is established, these values are exchanged and the lower value is used.

RemoteCodePageTR (Code page for transaction routing)

Specifies the code page for transaction-routing data that is flowing between your CICS system and the remote system. If this code page is different from your system's code page, CICS converts transaction-routing data between the local code page and the code page that is specified by the RemoteCodePageTR attribute when sending or receiving data.

The code page that is specified by the RemoteCodePageTR attribute must be either the same as the local code page or one of the code pages that can be converted to and from the local code page. On Open Systems platforms, you can use the operating system utility iconv.

The RemoteCodePageTR attribute takes the following default values:

UNIX platforms and Linux:: ISO8859-1
Windows:: IBM-850

For more information, see Data conversion for transaction routing.

RemoteLUName (Name of remote system)

Specifies the name of the remote system. The value that is required depends on the ConnectionType attribute:

If ConnectionType is set to ppc_tcp, set RemoteLUName to the APPLID (region name) of the remote system.
If ConnectionType is set to local_sna or ppc_gateway, set RemoteLUName to the Logical Unit (LU) name of the remote system.
If ConnectionType is set to cics_tcp, set RemoteLUName to the APPLID of the remote system, unless the remote system is CICS OS/2.
If ConnectionType is set to cics_tcp and the remote system is CICS OS/2, set RemoteLUName to the NETNAME that is returned by the cicstcpnetname command.

The default value is "".

If the RemoteLUName is set to cics_ipic, set RemoteLUName to the APPLID of the remote system.

RemoteNetworkName (SNA network name for the remote system)

Specifies the name of the network to which the remote system is attached. The name can be no more than eight characters. If the remote system is connected by SNA, the value of this attribute must be the SNA network name of the remote system. If the remote system is connected by TCP/IP, the value of this attribute must be the network name, if any, that is defined in the remote system. In CICs, the network name of the system is specified in the attribute LocalNetworkName in the Region Definitions (RD).

The default value is "".

RemoteSysEncrypt (Transmission encryption level)

Specifies whether encryption is required, and if required, the type of encryption that is required. Possible values are none, control, and alldata. The default value is none. Because encryption is not currently supported, other values are ignored.

RemoteSysSecurity (Security level for inbound requests)

This attribute specifies how CICS is to process security information, such as user IDs and passwords, received with an inbound request. Three values are possible:

local: Specifies that all security information that is received is discarded, and assigns the user ID that is specified in the LinkUserId attribute to the request. (If the LinkUserId attribute is set to "", the user ID that is specified by the DefaultUserId attribute in the Region Definitions (RD) is used instead.)
verify: Specifies that only user IDs that are received with a valid password can be assigned to the inbound request. If the password is missing or incorrect, or if no user ID is sent, the user ID that is specified by the DefaultUserId attribute in the RD is to be used.
trusted: Specifies that user IDs that are received with or without a password are to be assigned to the request. If no user ID is sent, the user ID that is specified in the DefaultUserId attribute in the RD is used.

After the user ID is assigned, the Transaction Security Level (TSL) and Resource Security Level (RSL) keys are calculated for the request. The request is given the keys that are specified both in the User Definition (UD) entry for the assigned user ID and in the UD entry for the user ID that is specified in the LinkUserId attribute. If the value for the LinkUserId attribute is "", the keys from attributes RSLKeyMask and TSLKeyMask are used instead of the LinkUserId keys. For more information about when to use the different options for the value of the RemoteSysSecurity attribute and how it is affected by your network configuration, see Configuring intersystem security. The default value for RemoteSysSecurity is local.

RemoteTCPAddress (TCP address for the remote system)

Specifies the name or address of the network adapter for the remote system. It can be specified 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 Internet Protocol (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 defined in the Internet name service. For example, aix5.cicsland.com. This host name must refer to only one IP address.

The RemoteTCPAddress is required only if the ConnectionType attribute is set to cics_tcp or cics_ipic. The default value is "".

Note:

Dotted hexadecimal notation is not supported for IPIC protocol (cics_ipic). End of change

RemoteTCPPort (TCP port number for the remote system)

Specifies the number of the TCP/IP port on which the remote system is listening for requests. RemoteTCPPort is required only if the ConnectionType attribute is set to cics_tcp or cics_ipic. The default value is 1435 (if ConnectionType is set to cics_tcp), which is the port that is registered for CICS with the Internet Assigned Number Authority (IANA). RemoteTCPPort is mandatory if the ConnectionType is set to cics_ipic. Set this attribute to zero, if the CD entry belongs to a CICS Transaction Gateway client and if the ConnectionType is cics_ipic.

RemoteTCPIPFamily

This attribute specifies the type of TCP/IP family address to use for communication. Set this to ipv4 for using IPv4 addressing. Similarly, set it to ipv6 for using IPv6 address for communication.

The default value is ipv4. See Table 3.

ResourceDescription (Resource description)

Specifies this CD entry with a 30-byte string. The default value is "Communications Definition".

RSLKeyMask (Resource Security Level (RSL) Key Mask)

Specifies the list of resource link security keys that CICS uses to control access to resources from transactions. These keys are used only when a value for the LinkUserId attribute is not specified, as described in Configuring intersystem security.

You can specify up to 24 keys, each in the range 1 through 24 and separated by the vertical bar (|) character. The following example shows that resources with the RSLKeys 1, 2, eight, and 23 can be accessed:

1|2|eight|23

Alternatively, you can specify the value all, which allows access to all the transactions.

CICS takes the values that are common to the RSLKeyMask and the RSLKeylist attribute that is defined in the User Definitions (UD) entry for the user. The result of this operation specifies the actual resource security keys that are used for validation.

Note: Be aware of the effects of the RSL values public or private for a resource. With the setting public, any user can access the resource. With the setting private, CICS allows access to the resource only from transactions that have the attribute RSLCheck set to none in their Transaction Definitions (TD) entries. For more information, see Authorizing access to CICS resources from applications.

For more information about how this attribute is used for intersystem requests, see Configuring intersystem security.

The default value for RSLKeyMask attribute is none, which gives access to public transactions.

SendCount

Specifies, in the range 0-999, the number of send sessions; that is, sessions that send outgoing requests. The actual number of send sessions that are used depends also on the number of receive sessions defined in the remote system. When the connection is established, these values are exchanged and the lower value is used. If 0 is specified, then this IPCONN can only process incoming work. It cannot send requests to the connected system.

SendTaskInfo (Should task information be passed to the linked region)

Specifies whether task information should be passed to the linked region. If this attribute is set to yes then the current task information and the originating task information if any is passed to the remote region connected using EXEC CICS LINK. The default value is no.

SNAConnectName (SNA profile describing the remote system)

Used only for SNA connections. It specifies the name of the partner LU alias that is defined in your SNA product, and is required only if the partner LU alias is different from the LU name of the remote system. Do not code this field if the partner LU alias is the same as the value that is set for the RemoteLUName attribute. For the different requirements of each operating system, see Configuring CICS for SNA. The default value is "".

SupportedRecovery

Specifies the recovery protocol supported by the host system.

TSLKeyMask (Transaction Security Level (TSL) Key Mask)

Specifies the list of transaction link security keys that CICS uses to control access to transactions. These keys are used only when a value is not specified for the LinkUserId attribute, as described in Configuring intersystem security.

You can specify up to 64 keys, each in the range 1 through 64 and separated by the vertical bar character (|). The following example shows that transactions with the TSLKeys 1, 5, 13, and 52 can be accessed:

1|5|13|52

Alternatively, you can specify the value all, which allows access to all the transactions.

CICS takes the values that are common to the TSLKeyMask and the TSLKeyList attribute that is defined in the UD entry for the user. The result of this operation specifies the actual transaction security keys that are used for validation.

For more information about how this attribute is used for intersystem requests and for further information about transaction security, see Configuring intersystem security.

The default value for TSLKeyMask is none.