UPDATE IMSCON TYPE(RMTCICS) command
Use the UPDATE IMSCON TYPE(RMTCICS) command to stop or restart communication between an IMS Connect instance and a remote CICS® subsystem.
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(RMTCICS) command.
- NAME
- Specifies one or more remote CICS connection names to be updated. You can specify a single remote CICS connection name or a list of remote CICS connection names separated by commas. You can use wildcard characters in the names.
- START(COMM) | STOP(COMM)
- Mutually exclusive keywords that you use to start or stop communications
for the remote CICS connection.
- START(COMM)
- Starts the named remote CICS connection in IMS Connect. After issuing this command, the TCP/IP connection between IMS Connect and the remote CICS is enabled. However, if an ISC link was also stopped by the UPDATE IMSCON TYPE(ISC) STOP(COMM) command, to fully enable communications for ISC, you also need to issue the UPDATE IMSCON TYPE(ISC) START(COMM) command.
- STOP(COMM)
- Stops communications on the remote CICS connection.
When the UPDATE IMSCON TYPE(RMTCICS) STOP(COMM) command is issued, IMS Connect:
- Stops all communication with a remote CICS instance on the connection specified in the command.
- Informs IMS that the connection to the remote CICS instance has been stopped so that IMS can shut down any affected ISC parallel sessions.
- Terminates existing socket connections and prevents new socket connections until the UPDATE RMTCICS START(COMM) is issued.
- Changes the status of the connection to STOPPED.
- Issues message HWSV4405I.
If IMS Connect receives a message for a connection in the STOPPED state, IMS Connect returns a NAK response to IMS and issues message HWSG4040W. IMS retains the message at the front of the queue.
Usage notes
You can issue the UPDATE IMSCON TYPE(RMTCICS) 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.
Modifications that are made to IMS Connect resources by use of this command are not saved across restarts of IMS Connect.
When the UPDATE IMSCON TYPE(RMTCICS) START(COMM) command is issued, IMS Connect resumes communications on the specified connection to a remote CICS instance. IMS Connect changes the status of the connection to NOT ACTIVE until new sockets are opened for communications with the remote instance of CICS.
The UPDATE IMSCON TYPE(RMTCICS) START(COMM) command is required only when communication on a connection with a remote CICS instance have been previously stopped by an UPDATE RMTCICS STOP(COMM) command.
For ISC communications, the UPDATE IMSCON TYPE(RMTCICS) START(COMM) command resumes only TCP/IP communications in IMS Connect, and does not change the stopped status of ISC links. If the ISC links have been stopped by an UPDATE IMSCON TYPE(ISC) STOP(COMM) command, after you issue the UPDATE IMSCON TYPE(RMTCICS) START(COMM) command, you also need to restart the ISC links in IMS Connect by issuing the UPDATE IMSCON TYPE(ISC) START(COMM) command.
Use the QUERY IMSCON TYPE(RMTCICS) command to display information about the current connections to a remote CICS instance that are defined to the local IMS Connect instance.
Equivalent WTOR and z/OS commands
The UPDATE IMSCON TYPE(RMTCICS) command does not have an equivalent WTOR or z/OS® MODIFY 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(RMTCICS) command | Equivalent IMS Connect WTOR command | Equivalent IMS Connect z/OS command |
|---|---|---|
| UPDATE IMSCON TYPE(RMTCICS) NAME(*) START(COMM) | None | None |
| UPDATE IMSCON TYPE(RMTCICS) NAME(rmtcics_name) STOP(COMM) | None | None |
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. See Table 4. |
| 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. |
| MBR | MbrName | N/A | Identifier of the IMS Connect that built the output line. The identifier is always returned. |
| RCICS | RmtCICS | N/A | Identifier of the remote CICS connection to be acted upon. The identifier is always returned. |
Return, reason, and completion codes
The return and reason codes that can be returned as a result of the UPDATE IMSCON TYPE(RMTCICS) 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(RMTCICS) command completed successfully. The command output contains a line for each resource, accompanied by its completion code. |
| X'0C000008' | X'00002004' | An invalid keyword or keyword parameter was specified. |
| X'0C000008' | X'00002014' | An invalid character was specified in the NAME() parameter. |
| X'0C000008' | X'00002018' | The NAME keyword was not specified, but is a required keyword for the UPDATE IMSCON TYPE(RMTCICS) command. |
| X'0C000008' | X'00002020' | Neither the STOP keyword nor the START keyword was specified. One of these must be specified. |
| X'0C000008' | X'00002044' | The STOP and START keywords were both specified in the command. Only one of these may be specified. |
| 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. |
| X'0C000014' | X'00005000' | The command processor failed to obtain storage via BPECBGET. |
| X'0C000014' | X'00005050' | The command processor was unable to stop the RMTCICS connection. |
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(RMTCICS) command completed successfully for the resources. | |
| A | TRWB creation failed | The command attempted to create a TWU block for the RMTCICS connection, but the attempt failed. Refer to message HWSV4415W which is included in the command output. |
| C | Create scheduler thread failed | The command attempted to create a BPE thread for the RMTCICS scheduler, but the attempt failed. Refer to message HWSV4415W which is included in the command output. |
| 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 | The command could not stop a RMTCICS connection because it was already stopped. |
| 12 | Resource is not stopped | The command could not start a RMTCICS connection because it was not stopped. |
| 1A | BPEGETM error | The command attempted to obtain storage needed for the RMTCICS connection, but the BPEGETM attempt failed. Refer to message HWSV4630W, which is included in the command output. |
| 1E | BPEATTCH failed | The command attempted to attach a TCB for the RMTCICS connection, but the BPEATTCH attempt failed. Refer to message HWSV4415W, which is included in the command output. |
| 1F | BPX1GAI get ipaddr failed | The command attempted to obtain the IP address of the CICS system, but the BPX1GAI call to TCP/IP failed. Refer to message HWSV4600E, which is included in the command output. |
| 23 | BPX1GAI invalid IPV4/6 struct | The command attempted to obtain the IP address of the CICS system, but the BPX1GAI call to TCP/IP returned an invalid IP address structure that was neither IPV4 or IPV6. Refer to message HWSV4600E, which is included in the command output. |
| 24 | BPX1FAI free structure failed | The command attempted to return storage that was returned by TCP/IP in the BPX1GAI call, but the BPX1FAI call to free the storage failed. Refer to message HWSV4600E, which is included in the command output. |
Example of the UPDATE IMSCON TYPE(RMTCICS) command
In the following example, the UPDATE IMSCON TYPE(RMTCICS) command is used to start the remote CICS connection CONNECT2.
TSO SPOC input:
UPD IMSCON TYPE(RMTCICS) NAME(CICS4) START(COMM)TSO SPOC output:
RmtCICS MbrName CC
CICS4 HWS1 0 OM API input:
CMD ( UPD IMSCON TYPE(RMTCICS) NAME(CICS4) START(COMM) )OM API output:
<imsout>
<ctl>
<omname>OM1OM </omname>
<omvsn>1.6.0</omvsn>
<xmlvsn>20 </xmlvsn>
<statime>2012.230 23:13:59.998357</statime>
<stotime>2012.230 23:14:00.007729</stotime>
<staseq>CA08E99671795E1A</staseq>
<stoseq>CA08E99673C31A9A</stoseq>
<rqsttkn1>USRID01 10161359</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(RMTCICS) NAME(CICS4) START(COMM) </input>
</cmd>
<cmdrsphdr>
<hdr slbl="RCICS" llbl="RmtCICS" scope="LCL" sort="a" key="2"
scroll="no" len="8" dtype="CHAR" align="left" skipb="no" />
<hdr slbl="MBR" llbl="MbrName" scope="LCL" sort="a" key="1" 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>RCICS(CICS4 ) MBR(HWS1 ) CC( 0) </rsp>
</cmdrspdata>
</imsout>