UPDATE MSLINK command

The UPDATE MSLINK command can be either a type-1 or type-2 command.

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Output fields
• Return, reason, and completion codes
• Examples

Environment

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

Syntax

Type-1 command syntax

>>-+-/UPDATE-+--MSLINK--NAME(linkname)-------------------------->
   '-/UPD----'                           

        .-,------------------------.     
        V                          |     
>--SET(---+-BANDWIDTH(-+-ON--+-)-+-+-)-------------------------><
          |            '-OFF-'   |       
          '-BUFSIZE(new_bufsize)-'       

Type-2 command syntax

                               .-,-------------.       
                               V               |       
>>-+-UPDATE-+--MSLINK--+-NAME(---+-linkname--+-+-)-+------------>
   '-UPD----'          |         '-linkname*-'     |   
                       '-NAME(*)-------------------'   

   .-,---------.   
   V           |   
>----+-| A |-+-+-----------------------------------------------><
     +-| B |-+     
     '-| C |-'     

A

        .-,--------------------------------.     
        V                                  |     
|--SET(---+-ASR(-+-ON--+-)---------------+-+-)------------------|
          |      '-OFF-'                 |       
          +-BANDWIDTH(-+-ON--+-)---------+       
          |            '-OFF-'           |       
          +-BUFSIZE(new_bufsize)---------+       
          +-MODETBL(-+---------------+-)-+       
          |          '-modetablename-'   |       
          +-MSLINK(new_linkname)---------+       
          +-MSPLINK(msplinkname)---------+       
          +-PARTNER(partner_id)----------+       
          '-SYNCOPT(-+-FORCSESS-+-)------'       
                     +-SYNCSESS-+                
                     '-COLDSESS-'                

B

          .-,--------------.                
          V                |                
|--START(---+-COMM-------+-+-)--+-------+-----------------------|
            +-TRACE------+      '-| D |-'   
            +-TKOTRC-----+                  
            '-STATISTICS-'                  

C

         .-,----------.                
         V            |                
|--STOP(---+-COMM---+-+-)--+-------+----------------------------|
           +-TRACE--+      '-| D |-'   
           '-TKOTRC-'                  

D

           .-,-----------.     
           V             |     
|--OPTION(---+-CHKPT---+-+-)------------------------------------|
             +-NORESET-+       
             +-RESET---+       
             '-FORCE---'       

Keywords

The following keywords are valid for the UPDATE MSLINK command:

NAME()

Specifies the 1- to 8-character name of the MSC logical links to be processed. You can specify wildcard parameters (*) for the NAME keyword. The logical link names are processed if they match the wildcard name. NAME(*) and NAME(abc*) are examples of valid names.

SET()

Specifies the updates to attributes or parameters. You cannot specify both the SET() parameter and the STOP(COMM) parameter.

ASR()

The Automatic Session Restart (ASR) designation of a VTAM® link changes when the Session Outage Notification facility of VTAM is used. The ASR parameter allows you to override the system definition option that is defined for the automatic session restart designation of a link.

You cannot change the designation of ASR for non-VTAM MSC links.

Stop the logical link before you change the ASR designation.

ON

Specifies that the logical link uses automatic session restart. Automatic session restart is not necessarily activated for a link if a status of ASR is displayed for that link. You must also specify SONSCIP=YES on the APPL definition statement for VTAM when defining the network to VTAM. ASR works only if both sides of the link are using the ASR option.

OFF

Specifies that the logical link does not use automatic session restart.

BANDWIDTH()

Specifies whether the logical link uses bandwidth mode.

The BANDWIDTH keyword does not apply to logical links assigned to a TCP/IP-type physical link. TCP/IP physical links always operate in bandwidth mode. If SET(BANDWIDTH(OFF)) is specified for a TCP/IP physical link, the command is rejected.

There is no system definition option to enable bandwidth mode. By default, logical links are initialized with bandwidth mode off.

To change the bandwidth mode, first stop the logical link. The link must not display a status ERE.

ON

Specifies that the logical link uses bandwidth mode.

OFF

Specifies that the logical link does not use bandwidth mode.

BUFSIZE()

Changes the input and output buffer sizes for the logical link. The minimum buffer size is 1024, and the maximum buffer size is 65536.

The logical link must be stopped before changing the BUFSIZE value. Buffer sizes for logical links follow the same specification requirements as buffer sizes specified on the MSPLINK macro by using the BUFSIZE= keyword.

MODETBL()

The default mode table name of a link changes if you specify the MODETBL() parameter without the START(COMM) parameter. This default is usually established by system definition. To reset this field to its null state (as if a mode table name was not specified at system definition), specify MODETBL().

If you specify both the START(COMM) parameter with the MODETBL() parameter, then the specified mode table name is used only for the START(COMM) session. When the session is terminated, the link mode table name reverts to the default mode table name.

The mode table name determines the mode table entries to be used when activating a VTAM MSC session. You cannot use the MODETBL keyword with non-VTAM sessions.

The logical link must be stopped before changing the MODETBL value.

MSLINK()

Specifies the 1- to 8-alphanumeric new link name for the specified logical link. If you specify the MSLINK parameter, you can specify only one NAME parameter. The new link name cannot already exist as a logical link name. If the command is successful, the link name specified on the NAME keyword is no longer valid.

The logical link must be stopped before changing the MSLINK name.

MSPLINK()

Enter the 1- to 8-character name of the MSC physical link to which you want to assign this logical link. You assign the logical link to the physical link for input and output purposes. The physical link name specified must already exist.

The logical link must be stopped before changing the MSPLINK. If the logical link is being assigned to either a TCP/IP physical link or a VTAM physical link, then the physical link must also be stopped. TCP/IP and VTAM physical links can be stopped by issuing the UPD MSPLINK NAME(plnkname) STOP(LOGON). If the TCP/IP physical link is used for TCP/IP generic resources, the physical link can be stopped with the UPD MSPLINK NAME(plnkname) STOP(GENLOGON) command.

If the logical link is being assigned to a TCP/IP physical link, bandwidth mode is turned on for the logical link. Bandwidth mode is always on for TCP/IP physical links and cannot be turned off.

If the logical link is being assigned to a CTC or MTM link, then the logical link that is currently assigned to the target physical link must also be stopped.

PARTNER()

Specifies the 2-character alphabetic partner identification. This partner identification ensures that the two related logical links in two systems are always logically and physically connected. Both systems must have logical links with the same partner ID. The new partner ID specified must not already exist.

Only one logical link can be specified in the NAME keyword to change the PARTNER keyword.

The logical link must be stopped before changing the PARTNER keyword.

SYNCOPT()

Specifies the system definition option to be overridden for the named logical link. This keyword allows the user to override the system definition option defined for forcing resynchronization until the next UPDATE MSLINK command is issued or IMS™ is cold started.

SYNCOPT() is valid only for TCP/IP and VTAM links.

The logical link must be stopped before changing SYNCOPT.

FORCSESS

Specifies that the session initiation is to be completed regardless of the agreement between session restart modes and the message sequence numbers. Use of the FORCSESS parameter could cause messages to be lost or duplicated.

SYNCSESS

Specifies that the session initiation is to be completed only when the session restart modes and message sequence numbers agree.

COLDSESS

Resets the session restart mode to COLD by resetting all the MSLINK dynamic flags and fields to zero, which allows cold session initiation of the link. Use the COLDSESS parameter when attempts to warm start the session fail.

Use of the COLDSESS parameter could cause messages to be lost or duplicated.

Before issuing the command with the COLDSESS option, stop the link first. When COLDSESS is specified, it should be used on both sides of the link.

The COLDSESS parameter does not override the current setting of SYNCSESS or FORCSESS.

START()

Starts the specified MSC logical links, or starts tracing of the specified logical links.

COMM

Starts the specified MSC logical links and allows IMS to start sending and receiving messages.

Communication between IMS systems does not begin until an UPDATE MSLINK command is entered in both systems for CTC or MTM links, or in one of the systems for either a TCP/IP or a VTAM link.

The COMM parameter cannot be specified in both START() and STOP(). The logical link must be stopped and idle, and the assigned physical link must be open, as shown in the QUERY command output.

TRACE

Turns on the tracing of internal IMS events that are related to the specified logical links. Unlike the equivalent type-1 /TRACE command, the trace level cannot be specified on the UPDATE command. Instead, IMS uses the default level of 4. The status and options of the current IMS traces can be displayed with the QUERY MSLINK command. TRACE cannot be specified in both START() and STOP().

Note: The type-2 command UPDATE MSLINK NAME(linkname) START(TRACE) uses the same level and module settings that were used the last time the /TRACE SET (ON) LINK command was issued. If a /TRACE SET (ON) LINK command has not been issued since the last cold start, this command defaults to MODULE=ALL and LEVEL=4.

TKOTRC

Enables tracing during takeover. This tracing is separate from regular tracing. This keyword applies only in an XRF environment. TRACE and TKOTRC cannot both be specified under START(). TKOTRC cannot be specified in both START() and STOP().

STATISTICS

Provides statistics support to MSC logical links. These statistics can be used to determine the link performance, adjust the link and message queue buffer sizes to optimum sizes, and increase the link performance. Each logical link (MSLINK) has a work area where statistics are kept.

STOP()

Stops the specified MSC logical links or stops tracing of the specified logical links.

COMM

Stops the specified MSC logical links, and allows IMS to stop sending and receiving messages. The partner link in another IMS system stops itself. COMM cannot be specified in both START() and STOP(). You cannot specify both STOP(COMM) and SET() together.

TRACE

Turns off the tracing of internal IMS events that are related to the specified logical links. The status and options of the current IMS traces can be displayed with the QUERY MSLINK command. TRACE cannot be specified in both START() and STOP().

TKOTRC()

Disables tracing during takeover. This tracing is separate from regular tracing. This keyword applies only in an XRF environment. TKOTRC cannot be specified in both START() and STOP().

OPTION()

Specifies options for the UPDATE MSLINK command. OPTION is valid only with START(STATISTICS) or STOP(COMM).

FORCE

Can be specified only with STOP(COMM) for CTC, TCP/IP, and VTAM links. Use the FORCE parameter when an MSC link does not clean up and assume a PSTOP IDLE status in IMS after normal UPDATE STOP(COMM) processing, even though the session has been terminated.

After using the FORCE parameter, issue the UPDATE MSLINK command with the NAME(linkname | *) START(COMM) options to restart the link.

For TCP/IP links, the FORCE option is useful for shutting down an MSC TCP/IP link that did not shut down normally after the link was shut down in the partner IMS system. You are not required to shut down a link normally before using the FORCE option.

FORCE also notifies the local IMS Connect instance to clean up sessions for TCP/IP links and VTAM to clean up sessions for VTAM links.

IMS performs the following actions when processing the FORCE option for a TCP/IP link:

• Shuts down the link in the IMS where the command is issued
• Notifies the local IMS Connect instance to clean up the send socket
• Issues an error message
• Places the link in ERE IDLE status

For VTAM links, you can use the FORCE parameter with some network commands to clean up the VTAM link within IMS.

RESET | NORESET

Issuing the UPDATE MSLINK() START(STATISTICS) OPTION(RESET) command will reset the link statistics and set the start time to the current time. The logical link does not need to be stopped and idle to reset the statistics values, or the reset mode, as is the case for changing many of the link characteristics, such as buffer size and bandwidth mode.

OPTION(RESET), OPTION(CHKPT,RESET), and OPTION(CHKPT, NORESET) can be specified with START(STATISTICS).

RESET

When specified without CHKPT, this indicates that statistics for the specified logical link should be reset immediately. When specified with CHKPT, this indicates that statistics for the specified logical link should be reset at every system checkpoint. This only applies to statistics reported on the QUERY MSLINK command. Statistics reported in the log records during system checkpoints are cumulative over the life of IMS, and are not reset by the UPDATE MSLINK command.

NORESET

When specified with CHKPT, this indicates that statistics for the specified logical link should not be reset at any system checkpoint. This only applies to statistics reported on the QUERY MSLINK command. Statistics reported in the log records during system checkpoints are cumulative over the life of IMS, and are not reset by the UPDATE MSLINK command.

CHKPT

When specified with RESET, this indicates that statistics for the specified logical link should be reset at every system checkpoint. When specified with NORESET, this indicates that statistics for the specified logical link should not be reset at any system checkpoint. This only applies to statistics reported on the QUERY MSLINK command. Statistics reported in the log records during system checkpoints are cumulative over the life of IMS, and are not reset by the UPDATE MSLINK command.

OPTION(CHKPT,RESET) and OPTION(CHKPT, NORESET) can be specified with START(STATISTICS).

Usage notes

You can issue the type-2 UPDATE MSLINK command only through the Operations Manager (OM) API. This command applies to DB/DC and DCCTL systems.

The syntax for the UPDATE MSLINK command is defined in XML and the syntax is available to automation programs that communicate with OM.

The UPDATE MSLINK command compared to other commands

The following table shows variations of the UPDATE MSLINK command and the type-1 IMS commands that perform similar functions.

Output fields

Short label

Contains the short label that is generated in the XML output.

Keyword

Identifies the keyword on the command that caused the field to be generated. error appears for output fields that can appear for a non-zero completion code. N/A (not applicable) appears for output fields that are always returned.

Meaning

Provides a brief description of the output field.

Return, reason, and completion codes

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

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.

Errors that are unique to the processing of the UPDATE MSLINK command are returned as completion codes. A completion code is returned for each action against an individual resource.

If the UPDATE MSLINK command is entered as a type-2 command, a message that contains the completion codes will be issued. The codes listed in the following table are for a type-1 UDPATE MSLINK command.

Table 5. Completion codes for the UPDATE MSLINK command

Completion code	Completion code text	Meaning
0		The UPDATE MSLINK command completed successfully for the resource.
10	NO RESOURCES FOUND	MSLINK name is invalid, or the specified wildcard parameter does not match any resource names.
11	RESOURCE ALREADY EXISTS	The linkname specified in SET(MSLINK(linkname)) already exists as a logical link.
62	HIOP STORAGE ERROR	IMS was unable to obtain storage from the HIOP pool.
8D	RESOURCE IS NOT STOPPED	The logical link is not stopped. The link must be stopped for the updates specified.
100	INV SET KEYWORD FOR LINK TYPE	A keyword specified in SET() is invalid for the corresponding physical link type.
101	TARGET MSPLINK NOT STOPPED	The target physical link specified in SET(MSPLINK()) is not stopped.
102	TARGET MSLINK NOT STOPPED	The logical link that is currently assigned to the target physical link specified in SET(MSPLINK()) is not stopped.
103	NEW PARTNER ID ALREADY EXISTS	The new partner ID specified in SET(PARTNER()) already exists.
104	MSLINK NOT ASSIGNED TO MSPLINK	The update cannot be performed because the logical link is not assigned to a physical link.
105	MSPLINK NOT OPEN	The update cannot be performed because the assigned physical link is not open.
106	INVALID OPTION FOR LINK TYPE	A keyword specified in OPTION() is invalid for the corresponding physical link type.
107	OPTION=FORCE ALREADY IN EFFECT	OPTION(FORCE) has already been invoked for the logical link.