Technical Notes
This chapter contains technical information that may be helpful when installing and administering ChangeMan ZDD.
TCP/IP Trouble Shooting
This section provides advice to the installer responsible for making Sernet connect to the TCP/IP address space.
Verifying the TCP/IP Port
A common concern is whether Sernet is listening on the proper port. Enter the following command on the ISPF Command Shell command line, or at the TSO READY prompt, to display a list of sockets and their corresponding states:
NETSTAT ALLCONN
The NETSTAT command can produce a high volume of output in a large network. The REPORT option can be added to the command to write the output to a data set. The syntax for adding the REPORT option is:
NETSTAT ALLCONN REPORT
The naming convention for the output data set is:
userid.NETSTAT.ALLCONN
The output of this command displays all ports currently in use. If for some reason Sernet cannot establish a TCP/IP connection and produces an appropriate error message at startup, then shut down the server address space and verify that no other address space currently uses this port. If the port is in use, you can either choose another port in the Sernet parmlib, or terminate, causing the other consumer to release the port. A single port can only be used by a single consumer at a time.
Detecting Errors in the TCP/IP API
Error messages from the TCP/IP API are written to the SERPRINT sysout data set for the Sernet started task. You can toggle the Sernet keyword option TRACE to see a complete listing of all TCP/IP calls. (Contact Customer Care about using TRACE.)
Each call to the API is detailed in messages with the following format:
SER0000I user-ID TCP/IP function RC=rc,ERRNO=errno
To find the specific reason for the error, locate the error number (errno) in Appendix D.1 of the IBM publication TCP/IP for MVS: API Reference. Function (function) and return code (rc) offer further advice.
Note
errno is a decimal and not a hexadecimal number.
Verifying Network Connectivity
Use the PING command to verify network connectivity to a specific IP address.
PING YOURLPAR
PING 111.111.111.111
Note
PING only verifies that network connectivity exists. It cannot determine if a specific port number is available for connection.
This method is not fool-proof, as some networks intentionally suppress the response to a PING command to lower the risk of intrusion. However, a positive response indicates basic connectivity.
Alternatively, you may use the TRACERTE TSO command. This command outputs the addresses of all capable devices along the route to a given destination. For example:
tracerte 10.31.224.91
might produce the following:
CS V1R8: Traceroute to 10.31.224.91 (10.31.224.91)...
1 10.35.2.20 (10.35.2.20) 2 ms 1 ms 1 ms
2 10.0.0.1 (10.0.0.1) 99 ms 98 ms 98 ms
3 OR-CVPN3030.company.com (10.31.2.40) 100 ms 99 ms 100 ms
4 rm04175.company.com (10.31.224.91) 185 ms 179 ms 179 ms
where each line indicates a "hop". This, too, is not necessarily a foolproof method and only a positive response verifies basic connectivity.
Examining Startup Messages
When Sernet is started, it issues a number of messages indicating the ports it uses and its IP address (the local IP address of the server). Whenever a connection to Sernet is made, these ports and IP addresses must be specified. The messages are:
SER1000I XCH TCP/IP environment active at 10.35.11.101..6021
SER1001I XCH TCP/IP local host name: D001
SER1000I CMN TCP/IP environment active at 10.35.11.101..6011
SER1001I CMN TCP/IP local host name: D001
Note that message SER1001I can only display a domain name if a domain name exists for the current address. When multiple domain name entries exist in a referenced domain name server (which is perfectly legal), only one of them will be printed.
Sernet will generally display at least two ports, one corresponding to the server address space itself, and the other catering to ChangeMan ZMF.
If you are using a different symbolic name than the one shown to connect to Sernet, you can verify that the domain name pointer references the proper address by using the NSLOOKUP TSO command:
For example:
NSLOOKUP D001
should produce:
EZB3170I Server: rcd-dc.company.com
EZB3172I Address: 10.30.11.10
which matches the output that Sernet has generated.
Attaching and Detaching TCP/IP Connections
If TCP/IP comes down while ChangeMan ZMF is up, the users cannot sign back on. This section describes how to recover from a TCP/IP outage using the following operator commands:
TCPIP,STOP,[mins]
TCPIP,START,[name]
TCPIP,RESTART,[mins],[name]
These commands provide the means for:
- Gracefully shutting down all TCP/IP connected users while not interrupting cross- memory connected users.
- Forcefully shutting down all TCP/IP connected users without impacting cross-memory connected users. This function is able to execute even in case of a complete TCP/IP failure.
- Terminating the TCP/IP API (TERMAPI).
- Re-initializing the API (and subsequent re-logon of TCP/IP users), optionally providing the name of an alternate TCP/IP (stack).
TCPIP,STOP,[mins]
This command displays the current users that are connected by ports. If no interval ([mins]) is specified, 0 minutes are assumed.
As soon as the command has been entered, no further TCP/IP connections are accepted.
A warning will be issued to all TCP/IP connected users every minute up to [mins] minutes, after which the TCP/IP users are terminated. This is done using standard termination post to SERUSER (involving cleanup).
After all TCP/IP users are terminated, the controlling task (SERMAIN) calls SERCOMM to close the socket and process a TERMAPI.
Also, at the top level, SERVER will process a TERMAPI via call to SERCOMM. This will always occur immediately.
The following display shows a sample sysout from the TCP/IP,STOP command:
NC0000000 C001 2008188 11:28:50.97 DYOUNG 00000280 F SERT3TMP,TCPIP,STOP
N FFDF000 C001 2008188 11:28:51.28 S0466400 00000080 SER0916I TCPIP Stop Requested
N FFDF000 C001 2008188 11:28:51.28 S0466400 00000080 SER0920I Current Users:0 Maximum Users:767
N FFDF000 C001 2008188 11:28:51.28 S0466400 00000080 SER2010I XCH ###<User_ID><T_Elapsed><T_LastAct><Partner
Identifier>
S Users=0
N FFDF000 C001 2008188 11:28:51.28 S0466400 00000080 SER2012I XCH No active users found
N FFDF000 C001 2008188 11:28:51.30 S0466400 00000080 SER2010I CMN ###<User_ID><T_Elapsed><T_LastAct><Partner
Identifier>
S Users=0
N FFDF000 C001 2008188 11:28:51.30 S0466400 00000080 SER2012I CMN No active users found
ISFPCU41 UT DISPLAY SERT3TMP S0466400 DSID 2 LINE 50 COLUMNS 02- 161
COMMAND INPUT ===> SCROLL ===> PAGE
11.28.51 S0466400 SER0916I TCPIP Stop Requested
11.28.51 S0466400 SER0920I Current Users:0 Maximum Users:767
11.28.51 S0466400 SER2010I XCH ###<User_ID><T_Elapsed><T_LastAct><Partner Identifier> Users=0
11.28.51 S0466400 SER2012I XCH No active users found
11.28.51 S0466400 SER2010I CMN ###<User_ID><T_Elapsed><T_LastAct><Partner Identifier> Users=0
TCPIP,START,[name]
This command starts TCP/IP communications (INITAPI) provided that the TCP/IP API has not already been initialized.
If the second parameter ([name]) has been specified, INITIAPI (SERCOMM) explicitly specifies this STC stack name when creating the TCP/IP environment.
When [name] has not been specified the code will connect to the default STC stack TCPIP or leave the selection up to the TCP/IP code which parses the SYSTCPD DD statement.
The following display shows a sample sysout from the TCP/IP,START command:
N FFDF000 C001 2008188 11:30:52.71 S0466400 00000080 SER0915I TCPIP Start Requested
N FFDF000 C001 2008188 11:30:52.78 S0466400 00000080 SER1000I CMNSTART TCP/IP environment active at 10.35.11.100..6031
N FFDF000 C001 2008188 11:30:52.78 S0466400 00000080 SER1001I CMNSTART TCP/IP local host name: C001
11.30.52 S0466400 SER0915I TCPIP Start Requested
11.30.52 S0466400 SER1000I CMNSTART TCP/IP environment active at 10.35.11.100..6031
11.30.52 S0466400 SER1001I CMNSTART TCP/IP local host name: C001
TCPIP,RESTART,[mins],[name]
The RESTART command will display the active TCP/IP users and stop accepting TCP/IP connection requests. It is a combination of the STOP and START command and will behave exactly as if the STOP and START commands had been issued one after the other.
Note
The individual usage of STOP and START commands allows the customer to recycle his TCP/IP STC. Before doing so, the existing TCP/IP users can be gracefully disconnected by using the TCPIP STOP command.
The (optional) parameter [mins] defines how long to allow for a voluntary logoff of the TCP/IP connected users. A warning will be issued to all TCP/IP connected users every
minute up to [mins] minutes, after which the TCP/IP users are terminated. This is done using standard termination post to SERUSER (involving cleanup).
After all TCP/IP users are terminated, the controlling task (SERMAIN) calls SERCOMM to close the socket and process a TERMAPI. Also, at the top level, SERVER will process a TERMAPI via call to SERCOMM. This will always occur immediately.
Immediately after the TERMAPI has completed, an INITAPI is again issued, making the address space available again for TCP/IP clients.
An optional TCP/IP STC name [name] may be specified, overriding the TCP/IP default.
The second RESTART format, that is, with [name] specified, is most useful when the customer wishes to switch TCP/IP stacks by specifying the optional name parameter.
The following display shows a sample sysout from the TCP/IP,RESTART command:
NC0000000 C001 2008188 11:42:22.36 DYOUNG 00000280 F SERT3TMP,TCPIP,RESTART
N FFDF000 C001 2008188 11:42:22.55 S0468486 00000080 SER0917I TCPIP Restart Requested
N FFDF000 C001 2008188 11:42:22.55 S0468486 00000080 SER0920I Current Users:0 Maximum Users:767
N FFDF000 C001 2008188 11:42:22.55 S0468486 00000080 SER2010I XCH ###<User_ID><T_Elapsed><T_LastAct><Partner
Identifier>
S Users=0
N FFDF000 C001 2008188 11:42:22.55 S0468486 00000080 SER2012I XCH No active users found
N FFDF000 C001 2008188 11:42:22.57 S0468486 00000080 SER2010I CMN ###<User_ID><T_Elapsed><T_LastAct><Partner
Identifier>
S Users=0
N FFDF000 C001 2008188 11:42:22.57 S0468486 00000080 SER2012I CMN No active users found
N FFDF000 C001 2008188 11:42:22.65 S0468486 00000080 SER1000I XCH TCP/IP environment active at 10.35.11.100..60
N FFDF000 C001 2008188 11:42:22.65 S0468486 00000080 SER1001I XCH TCP/IP local host name: C001
ISFPCU41 UT DISPLAY SERT3TMP S0468486 DSID 2 LINE 38 COLUMNS 02- 161
COMMAND INPUT ===> SCROLL ===> PAGE
11.42.22 S0468486 SER0917I TCPIP Restart Requested
11.42.22 S0468486 SER0920I Current Users:0 Maximum Users:767
11.42.22 S0468486 SER2010I XCH ###<User_ID><T_Elapsed><T_LastAct><Partner Identifier> Users=0
11.42.22 S0468486 SER2012I XCH No active users found
11.42.22 S0468486 SER2010I CMN ###<User_ID><T_Elapsed><T_LastAct><Partner Identifier> Users=0
11.42.22 S0468486 SER2012I CMN No active users found
11.42.22 S0468486 SER1000I XCH TCP/IP environment active at 10.35.11.100..60
11.42.22 S0468486 SER1001I XCH TCP/IP local host name: C001