MSPLINK macro

The MSPLINK macro defines an MSC physical link.

You can define an MSC physical link to use any one of the following types of connection between two systems:

  • Channel-to-channel connection (CTC)
  • Main-storage to main-storage connection (MTM)
  • Transmission Control Protocol/Internet Protocol (TCP/IP)
  • Virtual Telecommunications Access Method (VTAM®)

You can define a maximum of 1018 physical links (MSPLINK macros) in an IMS system.

Dynamic definition

Physical links can be defined dynamically with the CREATE MSPLINK command, instead of defining them statically with the system definition MSPLINK macro.

Supported environments

The MSPLINK macro can be used in the DB/DC and DCCTL environments.

Syntax

Read syntax diagramSkip visual syntax diagramlabelMSPLINKADDR= addr,BACKUP=4XNO,BUFSIZE= size,DDNAME= ddname,LCLICON= icon_plex_name,LCLPLKID= icon_plink_id,MODETBL= mode table,NAME=VTAM_node_nameTCPIP_rmt_imsid,OPTIONS=NOASRASR,SESSION=1n,TYPE=CTCMTMTCPIPVTAM

Label field

The MSPLINK name specifies a 1- to 8-character alphanumeric name for this physical link. You must specify this name. This name is used (in the MSPLINK= keyword operand of the MSLINK macro) to assign a logical link to this physical link. You can change this name using the UPDATE MSPLINK command.

Positional parameters

The MSPLINK macro does not include positional parameters.

MSPLINK macro keyword parameters

To find which parameters apply to your IMS configuration, see Selecting the appropriate macros to define your system.

ADDR=
Specifies the address of the communication line or the address of the channel-to-channel adapter. The address value can be three or four hexadecimal digits. This operand is required for CTC link types and invalid for other link types.

All devices attached to the same channel as the CTC adapter must be accessible through an alternative channel. In addition, do not attach system resources (for example, paging devices) to the same channel as the CTC adapter.

You can change the value specified on the ADDR= keyword by using the type-2 UPDATE MSPLINK SET(ADDR(addr)) command.

BACKUP=
For XRF-capable IMS systems, controls the automatic restart of TCP/IP and VTAM links after an XRF takeover.
X is a numeric integer from 1 to 7, inclusive, that specifies the priority for reestablishing the session. The default is 4. Specifying BACKUP=NO suppresses the automatic restart of the MSC physical link.

Although BACKUP prioritizes the order in which IMS restarts TCP/IP and VTAM links, the active requests might be completed in any order because of variables such as internal VTAM conflicts and pacing, Internet Protocol network traffic, and so on.

You can change the value specified on the BACKUP= keyword by using the type-2 UPDATE MSPLINK SET(BACKUP(backup)) command.

BUFSIZE=

Specifies the input and output buffer sizes for each logical link assigned to this physical link.

Buffer sizes for all link types can range from 1024 bytes to 65536 bytes.

The same buffer size must be specified by the IMS systems at each end of a physical link.

IMS initializes the MSC link buffers to the size specified on the BUFSIZE parameter.

If you are using bandwidth mode, a BUFSIZE value of 1024 is too small to send multiple messages with one buffer. A value of at least 4096 is recommended.

After system definition, you can specify a different buffer size for individual logical links by using the type-2 command UPDATE MSLINK NAME(linkname) SET(BUFSIZE(new_bufsize)). The buffer sizes for individual logical links follow the same specification requirements as buffer sizes specified on the MSPLINK macro.

You can change the value specified on the BUFSIZE= keyword by using the type-2 UPDATE MSPLINK SET(BUFSIZE(bufsize)) command.

DDNAME=
The ddname of the JCL statement that describes this physical connection. This operand is required CTC link types and is invalid for MTM and VTAM link types.

If the CREATE MSPLINK command is used, the DDNAME is allocated dynamically.

Each name must begin with an alphanumeric character. The following names cannot be used as DD names: 
DFSRESLB   IMSLOG     IMSTFMT    MSDBINIT
DUMP       IMSLOGR    IMSUDUMP   PRINTDD
IEFRDER    IMSLOGR2   LGMSG      PROCLIB
IEFRDER2   IMSLOG2    MSDBCP1     QBLKS
IMSACB     IMSMON     MSDBCP2    SHMSG
IMSDBL     IMSRDS     MSDBDUMP
IMSDILIB   IMSSPA
LCLICON
For TCP/IP links, specifies the IMSplex name of the local IMS Connect instance that manages TCP/IP communications for this physical link. The name specified on the LCLICON parameter must match the name specified on the MEMBER parameter of either the MSC statement or the IMSplex statement in the IMS Connect configuration PROCLIB member (HWSCFGxx). The name specified on the LCLICON parameter must start with an alphabetic character and can be 1- to 8-alphanumeric characters long.
LCLPLKID
For TCP/IP links, specifies the name used by IMS Connect to identify this physical link. The name specified on the LCLPLKID parameter of the MSPLINK macro must match the name specified on the LCLPLKID parameter of the MSC statement that defines the physical link to the local IMS Connect instance that is managing TCP/IP communications for this link. The name specified on the LCLPLKID must start with an alphabetic character and can be 1 to 8 alphanumeric characters long.
MODETBL=
Specifies the name of the VTAM logon mode table entry (logon mode name) containing the SNA bind parameters to be used when a session is established for this terminal.

With MODETBL=, you can have a system definition specification for referencing an entry other than the default entry in the user VTAM logon mode table. Normally, the terminal operator specifies this mode table entry name when logging on to a terminal; this result was not possible, however, from the IMS master terminal because IMS initiated the session.

If MODETBL= is not specified at system definition, no functional or operational change affects the user.

If MODETBL= is specified at system definition, the specified entry name is used.

You can display the current MODETBL name for each assigned logical link by using either the /DISPLAY LINK command or the QUERY MSLINK command. You can override the MODETBL name by using:
  • The LOGON APPLID entry by the remote terminal operator
  • The VARY ACT, LOGON= command by the network terminal operator
  • The /RST or the /CHANGE command by the master terminal operator
  • Either the type-2 command UPDATE MSPLINK or UPDATE MSLINK through the Operations Manager API

The MODETBL= parameter is required for the IMS master terminal if the VTAM default mode table has not been configured specifically for the device to be used as the IMS master terminal.

Specifying MODETBL on the MSPLINK macro circumvents the requirement to specify the mode table entry when logging on to terminals that always require specification of the same mode table entry name.

If the terminal being defined is in another domain (that is, a cross-domain resource), the MODETBL parameter does not have to be specified.

Related reading: See z/OS® Communications Server: SNA Programming for additional information.

NAME=
For TCP/IP and VTAM physical link types, identifies the remote IMS system at the other end of this physical link.

For a TCP/IP physical link, specify the IMS ID of the remote IMS system.

For a VTAM physical link, specify the VTAM node name of the remote IMS system.

This keyword is required for VTAM and TCP/IP physical link types and is invalid for other link types.

For VTAM MSC physical links, NAME= must be the same as the label on the VTAM APPL statement for the remote system (that is, the minor node name). If the VTAM MSC physical link is communicating with an XRF complex, the node name must be the VTAM USERVAR associated with the partner IMS/XRF complex. If the ACBNAME parameter of the VTAM APPL statement is not specified, NAME= is the same as the application identification (APPLID=) specified on the IMS COMM macro statement in the remote system.

You can change the value specified on the NAME= keyword by using the type-2 IMS command UPDATE MSPLINK command.

OPTIONS=
The Session Outage Notification facility only, specifies automatic session restart on all logical links associated with physical links. The default is NOASR. ASR or NOASR in the MSLINK macro overrides ASR definitions on the MSPLINK macro.
To display the current ASR option you can use the type-1 command /DISPLAY. To change the current ASR option you can use either of the following commands:
  • The type-1 command /CHANGE
  • The type-2 command UPDATE MSPLINK NAME(msplinkname) SET(ASR(OFF|ON))

ASR works only if both sides of the link are using the ASR option.

SESSION=

For TCP/IP and VTAM physical link types only, specifies the number of parallel sessions that can be active for the physical link. Valid values are from 1 to 999. The default is 1.

With a large SESSION value, you can dynamically assign more logical links to the physical link than were originally assigned during system definition. The SESSION value can be increased at system startup by using JCL. For instructions, see the keyword NLXB described in Environments that support IMS.SDFSRESL procedures.

Because a given number of logical parallel sessions uses the same amount of storage for control blocks and buffers as would the same number of physical links, allocating many parallel sessions can use an excessive amount of common storage area. Predetermine how much common storage area you want to use.

You can change the value specified on the SESSION= keyword by using the type-2 UPDATE MSPLINK SET(SESSION(session)) command.

TYPE=
Defines the type of physical link being described. Valid parameters are CTC, MTM, TCPIP, and VTAM.
With the MTM type link, you can have more than one IMS system running in the same z/OS system without a hardware link.