CREATE MSLINK command

You can assign a logical link to a physical link when you define it or later by using either the IMS type-2 UPDATE MSLINK command or the type-1 /MSASSIGN LINK command.

You can define a maximum of 1018 logical links in an IMS system.

Subsections:

• Environment
• Syntax diagrams
• Keywords
• Usage notes
• Output fields
• Return and reason codes
• Completion codes
• Example of the CREATE MSLINK command

Environment

The following table lists the environments (DB/BC, DBCTL, and DCCTL) from which the command keywords can be issued.

Keywords

The following keywords are valid for the CREATE MSLINK command:

ASR(OFF | ON)

Specifies the Automatic Session Restart (ASR) when the Session Outage Notification facility is used. ASR(OFF) is the default.

ASR applies only to logical links that are assigned to VTAM physical links when both sides of the link are using the ASR option.

An ASR specification in the definition of a logical link overrides ASR specifications in the definitions of both terminals and physical links.

To display the current ASR setting you can use either of the following commands:

• The type-1 command /DISPLAY LINK
• The type-2 command QUERY MSLINK NAME(linkname) SHOW(STATUS)

To change the current ASR option you can use either of the following commands:

• The type-1 command /CHANGE LINK
• The type-2 command UPDATE MSLINK NAME(linkname) SET(ASR(OFF | ON))

BACKUP

For XRF-capable IMS systems, controls the automatic restart of TCP/IP and VTAM® links after an XRF takeover.

The specification of BACKUP in the definition of a logical link overrides any switching options that are specified in the definition of the associated physical link. Use only if HSB=YES is specified on the IMSCTRL macro.

The value of n is a numeric integer from 1 to 7, inclusive, that sets the priority for reestablishing the session. When either the BACKUP keyword is omitted or no value is specified for BACKUP in the definition of either the physical or logical link, the default is 4. NO suppresses the session recovery of the physical link at takeover.

BACKUP is an MSC physical link attribute that you can set by using the CREATE MSPLINK, CREATE MSLINK, or UPDATE MSPLINK command. You can display the physical link BACKUP value by using the QUERY MSPLINK and QUERY MSLINK commands.

Important: Even though BACKUP is a physical link attribute, the CREATE MSLINK NAME(linkname) SET(MSPLINK(msplinkname)) command can also change the BACKUP value of the specified physical link. You can use the QUERY MSPLINK command to display the updated BACKUP value. You can also use the QUERY MSLINK command and specify the MSC logical links, including the newly created logical link, that are assigned to the physical link to display the updated BACKUP value.

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, TCP/IP network traffic, and so on.

BANDWIDTH(OFF | ON)

Specifies whether the logical link uses bandwidth mode.

OFF

Specifies that the logical link does not use bandwidth mode. However, if the physical link type specified by MSPLINK parameter is TCPIP, the bandwidth mode is set on. OFF is the default.

ON

Specifies that the logical link uses bandwidth mode.

BUFSIZE

Specifies the input and output buffer sizes for the newly created logical link.

The valid range of buffer sizes for all link types is 1024 - 65536 bytes.

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

If BUFSIZE is specified, the created logical link sets its buffer size to the value that is passed by BUFSIZE parameter.

If BUFSIZE is not specified but MSPLINK is specified, the buffer size of the created logical link inherits the buffer size from its physical link.

If both BUFSIZE and MSPLINK parameters are not specified, the created logical link takes the default value 4096 for its buffer size.

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.

This function allows a specification for referencing an entry other than the default entry in the user's VTAM logon mode table.

With this function, if MODETBL is not specified, no functional or operational change affects the user.

If MODETBL is specified, the specified entry name is used.

You can display the current MODETBL name by using either the /DISPLAY LINK command or the QUERY MSLINK command. You can override the MODETBL name by using any of the following commands:

• The VARY ACT, LOGON= command by the network terminal operator
• The /RST LINK or the /CHANGE LINK command by the master terminal operator
• The type-2 command UPDATE MSLINK NAME(linkname) SET(MODETBL(modetablename)) through the OM API

If the VTAM-node=name being defined is in another domain (that is, a cross-domain resource), the MODETBL parameter need not be specified.

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

MSPLINK

Assigns the logical link to the specified physical link.

If MSPLINK is specified, the physical link must exist in the system. When the physical link is either a TCP/IP physical link or a VTAM physical link, it must be stopped. When the physical link is either a CTC physical link or a MTM physical link, it must not be assigned to a logical link.

If you do not specify this keyword, the logical link is not assigned to a physical link.

You can assign this logical link to a physical link later by using either the /MSASSIGN LINK command or the type-2 command UPDATE MSLINK NAME(linkname) SET(MSPLINK(msplinkname)).

You must assign the logical link to a physical link before communication can be established between the two systems.

PARTNER

A 2-character alphanumeric identification that associates this logical link with its associated logical definition in the partner IMS system. The partner ID ensures that the two related logical link definitions in the partner IMS systems are always logically and physically connected. Both systems must have logical links that are defined with the same partner ID. If the logical link is assigned to a different physical link, the two systems can still communicate through the logical link, which remains as defined.

You can modify the partner ID by using the type-2 command UPDATE MSLINK NAME(linkname) SET(PARTNER(partner-id)).

SYNCOPT(SYNCSESS | FORCSESS)

For logical links that are assigned to TCP/IP or VTAM physical links only, specifies the session resynchronization options for the logical link.

SYNCSESS

Indicates that session initiation is to be completed only if session resynchronization is successful. Successful session resynchronization occurs when the message sequence numbers of the two logical units in session agree, or when the sequence number of the sender is not less than the sequence number of the receiver. SYNCSESS is the default.

FORCSESS

Forces the session initiation to be completed regardless of whether session resynchronization is successful.

The SYNCOPT setting can be overridden by either the type-1 command /CHANGE LINK nn FORCSESS | SYNCSESS | COLDSESS or the type-2 command UPDATE MSLINK NAME(linkname) SET(SYNCOPT(FORCSESS | SYNCSESS | COLDSESS)).

Usage notes

The CREATE MSLINK command can be issued only through the Operations Manager API. These commands apply to DB/DC and DCCTL systems. The syntax for this command is defined in XML and is available to automation programs that communicate with OM.

The CREATE MSLINK NAME(mslinkname) command specified with SET(MSPLINK(msplinkname)) is rejected if at least one logical link attribute specified in the command (ASR, BACKUP, MODETBL, or SYNCOPT) conflicts with the physical link type. However, after the logical link is created, it can be reassigned to any type of physical link with an UPDATE MSLINK command or an /MSASSIGN command. If a logical link defined with attributes applicable to specific physical link types is reassigned to a different physical link type that does not support those attributes, they are ignored when the link is started. The attributes are still defined for the logical link and can be displayed.

Output fields

Return and reason codes

The OM return and reason codes that might be returned as a result of the CREATE MSLINK command are standard for all commands that are entered through the OM.

The following table includes the return and reason codes and a brief explanation of the codes. The return or reason code returned for the command might also indicate an error from a CSL request.

Completion codes

The following table includes an explanation of the completion codes.