UPDATE IMSCON TYPE(PORT) command
Use the UPDATE IMSCON TYPE(PORT) command to terminate listening on a TCP/IP port, to reestablish a TCP/IP connection to enable listening on a TCP/IP port, or to change port attributes.
Subsections:
Environment
- IMS Connect must be active and configured to communicate with the Common Service Layer (CSL) Structured Call Interface (SCI).
- A type-2 command environment with Structured Call Interface (SCI) and Operations Manager (OM) must be active.
Syntax
Keywords
The following keywords are valid for the UPDATE IMSCON TYPE(PORT) command.
- NAME
- Specifies the names of one or more ports. You can specify a single
port name or a list of port names separated by commas. Wildcards can
be used in the names. The port name must match a port defined to IMS Connect on
one of the configuration statements in the IMS Connect PROCLIB
member or by using the CREATE
IMSCON TYPE(PORT) command..
To update the local port used by the IMS TM Resource Adapter, specify NAME(LOCAL).
An SSL port is displayed with the character
S
appended to the end of the port number. To update the SSL port, specify the port number either with or without the characterS
appended to the end of the port number.A DRDA port for ODBM use is displayed with the character
D
appended to the end of the port number. To update the DRDA port, specify the port number either with or without the characterD
appended to the end of the port number.A port defined as a CICSPORT for receiving messages on an ISC link from a CICS® subsystem is displayed with the character
C
appended to the end of the port number. To update a CICSPORT port, specify the port number either with or without the characterC
appended to the end of the port number. - SET()
- Specifies the attribute values to be changed. The SET() keyword
cannot be used in conjunction with the keywords START() or STOP().
- EDITRTN(editexit_name)
- Specifies a 1- to 8-character alphanumeric name of the Port Message
Edit exit routine that can modify messages that do not conform to
standard message formats for IMS Connect.
The exit routine must be accessible to IMS Connect by
either JOBLIB, STEPLIB, or LinkList.
The Port Message Edit exit routine and the EDITRTN attribute are only valid for regular ports. Invalid port types are: LOCAL, ODBM, SSL, and CICS.
To set the EDITRTN attribute, the port must be in NOTACTIVE state by issuing the UPD IMSCON TYPE(PORT) STOP(COMM) command. If needed, run the command with the STOP(COMM) attribute prior to running the command with the EDITRTN attribute.
When IMS Connect is unable to load the specified Port Message Edit exit routine, it will use the previously defined, if any, Port Message Edit exit routine when the port is started.
To disable the use of the Port Message Edit exit routine, use a zero as the value for the EDITRTN parameter, EDITRTN(0). The name of the previously set Port Message Edit exit routine still shows in the output of the BPE DISPLAY USEREXIT command, but IMS Connect does not call the Port Message Edit exit routine.
The use of the BPE REFRESH USEREXIT command to refresh the existing Port Message Edit exit routine might produce unexpected results when the IMS Connect port is active, because the new copy of the exit becomes available immediately after command completion. This might affect both input and output messages for currently connected TCP/IP clients. The BPE REFRESH USEREXIT command is processed by BPE, so IMS Connect does not issue the TERM call to the old version of the exit or the INIT call to the new version of the exit. Instead of using the BPE REFRESH USEREXIT command to update the port's edit exit routine, try to use the UPD IMSCON TYPE(PORT) SET(EDITRTN) command with the current name of the Port Message Edit exit routine.
- IDLETO
-
For open socket connections on this port, specifies the timeout interval for connections that are idle and waiting in a RECV state for the next message. When the timeout interval expires, IMS Connect closes the socket connection due to inactivity.
The timeout interval is in hundredths of seconds. Timeout values can be from -1 to 2 147 483 647 (X'7FFFFFFF'). A value of 0 disables this timeout function which prevents inactive connections from timing out.
A value of -1 specifies that connections on the port use the global-level idle timeout value.
Unless -1 is specified, the port-level idle timeout value overrides the global-level idle timeout value.
This parameter is optional and applies only to persistent socket connections.
The IDLETO parameter is valid only for ports that are used for communication with IMS TM, which are defined by the PORT= and PORTID= parameters in the TCPIP statement of the IMS Connect HWSCFGxx configuration member or by the CREATE IMSCON TYPE(PORT) command.
- KEEPAV(keepalive_value)
- Specifies a numeric value for the TCP/IP KeepAlive interval for
sockets on this port. The KeepAlive interval is in seconds. The range
is from 0 to 2,147,460 seconds. If zero is specified, the TCP/IP stack
interval value is used.
The KEEPAV attribute is only valid for regular, DRDA, and CICS ports. Invalid port types are: LOCAL and SSL.
- PORTTMOT(timeout_value)
- Specifies a numeric value for the amount of time that IMS Connect waits
for the next input message from a client application that is connected
on a DRDA port before IMS Connect disconnects
the client. The timeout interval is in hundredths of a second. The
range is from 0 to 2,147,483,647 hundredths of a second. A value of
zero disables the timeout function.
The PORTTMOT attribute is only valid for DRDA ports. Invalid port types are: LOCAL, regular, SSL, and CICS.
- START(COMM) | STOP(COMM)
- Specifies to start or stop communication on the port.
- START(COMM)
- Starts communication on the port. Use the UPDATE IMSCON TYPE(PORT) START(COMM) command when communication stops between the IMS Connect and a TCP/IP port, but the IMS Connect has not terminated.
- STOP(COMM)
- Stops communication on the port. Work currently in progress can continue for existing clients. Only the listening for new request messages on the port is terminated immediately. When existing work has completed, the port is no longer active.
Usage notes
You can issue the UPDATE IMSCON TYPE(PORT) command only through the Operations Manager (OM) API.
IMS Connect can process IMS Connect type-2 commands only if the IMSplex from which the commands were issued has a status of ACTIVE.
Updates that are made to IMS Connect resources by use of this command are not saved across restarts of IMS Connect, unless the updates are also made to the corresponding configuration statement in the HWSCFGxx member of the IMS PROCLIB data set before the next restart.
A port must be stopped (in NOTACTIVE state) before its EDITRTN attribute can be updated with the UPDATE IMSCON TYPE(PORT) SET(EDITRTN()) command.
Equivalent WTOR and z/OS commands
The following table lists IMS Connect WTOR (Write to Operator with Reply) and IMS Connect z/OS® commands that perform similar functions as the UPDATE IMSCON TYPE(PORT) command.
- IMS Connect WTOR commands are replies to the outstanding IMS Connect reply message.
- IMS Connect z/OS commands are issued through the z/OS (MVS™) interface by using the IMS Connect jobname.
| UPDATE IMSCON TYPE(PORT) command | Equivalent IMS Connect WTOR command | Equivalent IMS Connect z/OS command |
|---|---|---|
| UDPATE IMSCON TYPE(PORT) NAME(port_name) START(COMM) | OPENPORT port_id | UPDATE PORT NAME(port_name) START(COMM) |
| STARTPT port_id | ||
| UDPATE IMSCON TYPE(PORT) NAME(port_name) STOP(COMM) | STOPPORT port_id | UPDATE PORT NAME(port_name) STOP(COMM) |
Output fields
- Short label
- Contains the short label that is generated in the XML output.
- Long label
- Contains the column heading displayed on the TSO SPOC screen.
- Keyword
- Identifies the keyword on the command that caused the field to be generated. N/A (not applicable) appears for output fields that are always returned. error appears for output fields that are returned only in the case of an error.
- Meaning
- Provides a brief description of the output field.
| Short label | Long label | Keyword | Meaning |
|---|---|---|---|
| CC | CC | N/A | Completion code that indicates whether IMS Connect was able to process the command for the specified resource. The completion code is always returned. |
| CCTXT | CCText | error | Completion code text that briefly explains the meaning of the nonzero completion code. This field is returned only for an error completion code. |
| ERRT | ErrorText | error | Error text that provides diagnostic information. Error text can be returned for a non-zero completion code and further explains the completion code. |
| MBR | MbrName | N/A | Identifier of the IMS Connect that built the output line. The identifier is always returned. |
| PORT | Port | N/A | The port number. The port number is always returned. If one of the following
characters is appended to the end of the port number, it indicates that the port is dedicated to a
particular purpose:
If "LOCAL" is displayed instead of a port number, the port is a local port that is used by the IMS TM Resource Adapter. |
Return and reason codes
The return and reason codes that can be returned as a result of the UPDATE IMSCON TYPE(PORT) 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.
| Return code | Reason code | Meaning |
|---|---|---|
| X'00000000' | X'00000000' | The UPDATE IMSCON TYPE(PORT) command completed successfully. The command output contains a line for each resource, accompanied by its completion code. |
| X'02000008' | X'0000203C' | The command entered contains an invalid keyword parameter value. The command was rejected. |
| X'0C000008' | X'0000209C' | The SET() keyword cannot be used in conjunction with the keywords START() or STOP(). |
| X'0C00000C' | X'00003000' | The command was successful for some resources but failed for others. The command output contains a line for each resource, accompanied by its completion code. |
| X'0C00000C' | X'00003004' | The command was not successful for any resource. The command output contains a line for each resource, accompanied by its completion code. |
Completion codes
Errors unique to the processing of this command are returned as completion codes. A completion code is returned for each action against an individual resource.
| Completion code | Completion code text | Meaning |
|---|---|---|
| 0 | The UPDATE IMSCON TYPE(PORT) command completed successfully for the resources. | |
| 3 | Some attributes not updated | The command was successful for some attributes. There is a separate line of output with its own completion code for each attribute that IMS Connect failed to set. |
| 10 | No resources found | The resource name is unknown to the client that is processing the request. The resource name might have been typed in error or the resource might not be active at this time. If a wildcard was specified in the command, there were no matches for the name. Confirm that the correct spelling of the resource name is specified on the command. |
| 11 | Resource is stopped | During STOP(COMM) processing, IMS Connect could not stop a port because it was already stopped. |
| 12 | Resource is not stopped | During START(COMM) processing, IMS Connect could not start a port because it was already started. |
| 14 | Resource is not stopped | The resource is not stopped. The resource must be stopped first to update the attribute that is displayed in the ErrorText column. |
| 17 | Attribute is invalid for rsc | The attribute that is displayed in the ErrorText column is invalid for this particular port. For example, the attribute might not be supported on a CICS or DRDA port. The attribute cannot be set. |
| 12 | Resource is not stopped | The resource is not stopped. To update attributes of this resource, it must be stopped first. |
| 37 | Continuing to retry command | IMS Connect
encountered an error while processing the command. It continues to retry processing of the command
in the background. The command output might also contain one of the following messages, to indicate
why the command failed:
|
| 38 | Unable to start port scheduler | IMS Connect was unable to start the port scheduler. The command output also contains the following message: HWSS0712W. |
| 3D | Start process was interrupted | START(COMM) processing was interrupted by another command or because IMS Connect is shutting down. The command output contains the following message: HWSS0770I. |
| 4B | Unable to load port edit routine | IMS Connect could not load the Port Message Edit exit routine. The name of the Port Message Edit exit routine is displayed in the ErrorText column. |
| 4C | Unable to update attribute | IMS Connect could not update the attribute that is displayed in the ErrorText column. |
Examples
Example 1 for UPDATE IMSCON TYPE(PORT) command
TSO SPOC input:
UDPATE IMSCON TYPE(PORT) NAME(9999) START(COMM)TSO SPOC output:
Port MbrName CC
9999 HWS1 0 OM API input:
CMD(UDPATE IMSCON TYPE(PORT) NAME(9999) START(COMM))OM API output:
<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.5.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2010.298 02:49:44.222509</statime>
<stotime>2010.298 02:49:44.225852</stotime>
<staseq>C6C785426A72DABA</staseq>
<stoseq>C6C785426B43C87A</stoseq>
<rqsttkn1>USRID01 10194944</rqsttkn1>
<rc>00000000</rc>
<rsn>00000000</rsn>
</ctl>
<cmd>
<master>HWS1 </master>
<userid>USRID01 </userid>
<verb>UPD </verb>
<kwd>IMSCON </kwd>
<input>UPD IMSCON TYPE(PORT) NAME(9999) START(COMM) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="PORT" llbl="Port" scope="LCL" sort="a" key="1" scroll="no"
len="8" dtype="CHAR" align="left"skipb="no" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="2" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" scroll="yes"
len="4" dtype="INT" align="right" skipb="no" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0"
scroll="yes" len="32" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 0) </rsp>
</cmdrspdata>
</imsout> Explanation: IMS Connect, HWS1, is now listening on the TCP/IP port 9999.
Example 2 for UPDATE IMSCON TYPE(PORT) command
TSO SPOC input:
UPDATE IMSCON TYPE(PORT) NAME(9999) START(COMM)TSO SPOC output:
IMSplex . . . . . : PLEX1
Routing . . . . . : HWS1
Start time. . . . : 2013.253 16:52:42.35
Stop time . . . . : 2013.253 16:52:42.35
Return code . . . : 0200000C
Reason code . . . : 00003008
Reason text . . . : None of the clients were successful.
Command master. . : HWS1
Return Reason
MbrName Code Code Reason text
-------- -------- -------- --------------
HWS1 0C00000C 00003004 No requests were successful
MbrName Messages
-------- -----------------------
HWS1 HWSP1415E TCP/IP SOCKET FUNCTION CALL FAILED; F=GETSOCK , R=-1, E=112,
M=SDOT, ID=9999Explanation: IMS Connect, HWS1, could not start communication on the TCP/IP port 9999, because a TCP/IP socket function call failed.
Example 3 for UPDATE IMSCON TYPE(PORT) command
TSO SPOC input:
UPDATE IMSCON TYPE(PORT) NAME(9999)
SET(KEEPAV(120000))TSO SPOC output:
Port MbrName CC
9999 HWS1 0OM API input:
CMD(UPD IMSCON TYPE(PORT) NAME(9999)
SET(KEEPAV(120000)))OM API output:
<?xml version="1.0"?>
<!DOCTYPE imsout SYSTEM "imsout.dtd">
<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.7.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2014.232 16:09:50.846238</statime>
<stotime>2014.232 16:09:50.846556</stotime>
<staseq>CDA221E31B91EFD4</staseq>
<stoseq>CDA221E31BA5CD54</stoseq>
<rqsttkn1>USRT011 10090950</rqsttkn1>
<rc>00000000</rc>
<rsn>00000000</rsn>
</ctl>
<cmd>
<master>HWS1 </master>
<userid>USRT011 </userid>
<verb>UPD </verb>
<kwd>IMSCON </kwd>
<input>UPDATE IMSCON TYPE(PORT) NAME(9999) SET(KEEPAV(120000)) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="PORT" llbl="Port" scope="LCL" sort="a" key="1" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="2" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" scroll="yes" len="4"
dtype="INT" align="right" skipb="no" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0" scroll="yes"
len="32" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 0) </rsp>
</cmdrspdata>
</imsout>Explanation: The KeepAlive interval (KEEPAV) attribute is set to 120,000 seconds for port 9999.
Example 4 for UPDATE IMSCON TYPE(PORT) command
TSO SPOC input:
UPDATE IMSCON TYPE(PORT) NAME(9999,7777)
SET(KEEPAV(120000),EDITRTN(HWSEDIT0),PORTTMOT(6000))TSO SPOC output:
Port MbrName CC CCText ErrorText
7777D HWS1 3 Command complete for some
7777D HWS1 17 Attribute is invalid for rsc EDITRTN
9999 HWS1 3 Command complete for some
9999 HWS1 14 Resource is not stopped EDITRTN
9999 HWS1 17 Attribute is invalid for rsc PORTTMOTOM API input:
CMD(UPDATE IMSCON TYPE(PORT) NAME(9999,7777)
SET(KEEPAV(120000),EDITRTN(HWSEDIT0),PORTTMOT(6000)))OM API output:
<?xml version="1.0"?>
<!DOCTYPE imsout SYSTEM "imsout.dtd">
<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.7.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2014.232 16:26:34.861722</statime>
<stotime>2014.232 16:26:34.862037</stotime>
<staseq>CDA225A09C89AE52</staseq>
<stoseq>CDA225A09C9D50D2</stoseq>
<rqsttkn1>USRT011 10092634</rqsttkn1>
<rc>0200000C</rc>
<rsn>00003008</rsn>
<rsnmsg>CSLN054I</rsnmsg>
<rsntxt>None of the clients were successful.</rsntxt>
</ctl>
<cmderr>
<mbr name="HWS1 ">
<typ>IMSCON </typ>
<rc>0C00000C</rc>
<rsn>00003004</rsn>
<rsntxt>No requests were successful </rsntxt>
</mbr>
</cmderr>
<cmd>
<master>HWS1 </master>
<userid>USRT011 </userid>
<verb>UPD </verb>
<kwd>IMSCON </kwd>
<input>UPDATE IMSCON TYPE(PORT) NAME(9999,7777)
SET(KEEPAV(120000),EDITRTN(HWSEDIT0),PORTTMOT(6000)) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="PORT" llbl="Port" scope="LCL" sort="a" key="1" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="2" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" scroll="yes" len="4"
dtype="INT" align="right" skipb="no" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0" scroll="yes"
len="32" dtype="CHAR" align="left" skipb="yes" />
<hdr slbl="ERRT" llbl="ErrorText" scope="LCL" sort="a" key="3" scroll="no"
len="16" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 14) CCTXT(Resource is not
stopped) ERRT(EDITRTN ) </rsp>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 17) CCTXT(Attribute is invalid
for rsc) ERRT(PORTTMOT ) </rsp>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 3) CCTXT(Command complete for
some) </rsp>
<rsp>PORT(7777D ) MBR(HWS1 ) CC( 17) CCTXT(Attribute is invalid
for rsc) ERRT(EDITRTN ) </rsp>
<rsp>PORT(7777D ) MBR(HWS1 ) CC( 3) CCTXT(Command complete for
some) </rsp>
</cmdrspdata>
</imsout>The command is attempting to set the KEEPAV, EDITRTN, and PORTTMOT attributes for regular port 9999 and DRDA port 7777.
For DRDA port 7777, some updates are successful. A separate completion code is displayed for each attribute update that is not successful. The Port Message Edit exit routine (EDITRTN) attribute is not valid for a DRDA port, so it is not set. The KeepAlive interval (KEEPAV) and the DRDA port timeout (PORTTMOT) attributes are set successfully since there no completion codes are returned for them.
For DRDA port 7777, the Port Message Edit exit routine (EDITRTN) attribute is not valid for a DRDA port, so none of the attributes for port 7777 are set.
Example 5 for UPDATE IMSCON TYPE(PORT) command
In the following example, the idle timeout value for connections on port 9999 is updated to 3000, or 30 seconds.
TSO SPOC input:
UPDATE IMSCON TYPE(PORT) NAME(9999) SET(IDLETO(3000))TSO SPOC output:
Port MbrName CC
9999 HWS1 0
OM API input:
CMD(UPDATE IMSCON TYPE(PORT) NAME(9999) SET(IDLETO(3000)))OM API output:
<cmd>
<master>HWS1 </master>
<userid>USRT002 </userid>
<verb>UPD </verb>
<kwd>IMSCON </kwd>
<input>UPDATE IMSCON TYPE(PORT) NAME(9999) SET(IDLETO(3000)) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="PORT" llbl="Port" scope="LCL" sort="a" key="1" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="2" scroll="no"
len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="CC" llbl="CC" scope="LCL" sort="n" key="0" scroll="yes"
len="4" dtype="INT" align="right" skipb="no" />
<hdr slbl="CCTXT" llbl="CCText" scope="LCL" sort="n" key="0"
scroll="yes" len="32" dtype="CHAR" align="left" skipb="yes" />
<hdr slbl="ERRT" llbl="ErrorText" scope="LCL" sort="a" key="3"
scroll="no" len="16" dtype="CHAR" align="left" skipb="yes" />
</cmdrsphdr>
<cmdrspdata>
<rsp>PORT(9999 ) MBR(HWS1 ) CC( 0) </rsp>
</cmdrspdata>