This document is an explanation and configuration guide for the Sybase Mainframe Connect (MFC) TCP/IP Listener and the new gatewayless handler introduced in MFC 15.0 ESD6. By default, when installing ESD6, MFC will continue to use the legacy gatewayless handler. Future releases of MFC will install the new handler by default.
The New Gatewayless Handler –
The purpose of the gatewayless handler is to permit two-tier connections (no gateway required) between the client and the MFC Server Option for CICS. Prior to the new handler introduced in ESD6, the listener started a separate instance of the handler for each connection. This meant that the maximum number of MFC server transactions running (not including the listener) would be n * 2 (where n equals the number of connections). This assumes that all of the connections are currently running RPC’s. A new user security exit has also been provided to allow customized security processing to be performed for each new connection.
By reducing the number of running transactions, the new handler reduces CICS resources and significantly speeds up processing for long-running connections, when the client sends multiple requests.
The new ESD6 gatewayless handler requires only one instance of the handler be started. This single instance manages all connections not currently under control of an RPC transaction.
Listener Processing Overview –
After a listener is initialized (either at CICS startup, or in response to the CICS Sockets control transaction “EZAO”), processing of incoming connections starts. Here is the processing flow of a single connection request:
- The listener accepts an incoming connection request. A new socket is created to allow TCP/IP communication with the client.
- The listener issues a TCP read to obtain the TDS login packet. Note: TDS (Tabular Data Stream) is the data communications format used by all Sybase products supporting Open Client and Open Server. (This is also true for ODBC clients. The Sybase ODBC driver translates the request into TDS prior to transmitting it via TCP/IP.)
- The listener reads the login packet and determines if the client is sending recognizable Sybase TDS data. If not, an error message is returned, and the connection terminated.
- The listener then determines if the incoming request is originating through Sybase Direct Connect (gateway) or directly from a Sybase Open Client program or other Sybase TDS product (gatewayless). The userid and password are then extracted from the login packet. Note: The initial data sent by other applications may be similar enough to TDS that it will not be detected as non-Sybase.
- The userid and password is then verified. If incorrect, an error message is sent to the client, and the connection is terminated. Note: the Userid/Password is verified through the use of the CICS “EXEC VERIFY” command. This is to ensure compatibility with ESMs (External Security Manager) other than RACF (such as Top Secret) and others.
- The listener then issues a GIVESOCKET request and starts the Gateway Handler (for gatewayed connections) or the Socket Handler (for gatewayless) transactions, passing the socket information as started transaction data. If the new ESD6 handler is in use, the listener will pass the socket information via an intrapartition transient data queue to an already started handler. Note: The handler transaction then issues a TAKESOCKET, checks if the userid is authorized to run the requested OSC application, and then starts that transaction.
- Once the handler transaction has taken the socket, the listener then closes out the socket, returning it back to the listener socket pool.
Since it would be very inefficient for the listener to process each incoming request in the synchronous manner described above, sockets are processed asynchronously as follows (with references to specific tasks in the above processing description):
- During periods of inactivity, the listener waits for an ECB (Event Control Block) to be posted by TCP/IP. TCP posts this ECB if any activity occurs on a socket within the listener’s socket pool.
- When the ECB is posted, the listener then checks if there is a new incoming connection request. If so, items 1 and 2 are processed.
- If any read requests have completed, those sockets are processed as described in items 4, 5, and 6.
- If any given sockets have been “taken” (the started handler transaction has issued a TAKESOCKET) those sockets are then processed according to item 7.
- If the “STRTCHK” feature (see below) is active, the listener then checks the list of sockets waiting for a handler transaction to start. If any sockets in this list have been waiting past the elapsed time interval, these sockets are taken back, an error message issued, and the socket closed.
- The listener goes back to waiting on the ECB, and repeats the process.
ESD6 Gatewayless Handler Overview -
The ESD6 Gatewayless Handler transaction is started by the listener during its initialization routine, and terminated by the listener when it is shut down. While in operation, the handler maintains a socket pool to hold connections not currently “owned” by an executing RPC transaction.
- During periods of inactivity, the handler waits for an ECB to be posted by TCP/IP, the listener, or an executing RPC. TCP posts the ECB when any activity occurs within the handler’s socket pool, the listener posts when it places a new connection into the transient data queue, and the RPC posts when it is returning a socket back to the handler or when the RPC has executed a TDFREE command.
- When the handler finds a new message from the listener on the TD Queue, it takes the socket, creates various control blocks, and waits until the socket signals that the language request or RPC data has been transmitted by the client.
- When the client has transmitted the RPC/Language Request data, the handler reads this data, determines the RPC/language request and whether the userid associated with the connection has authority to run the transaction. The user security exit (if provided) is also called at this time. The purpose of the exit is to allow the customer to provide a specific RACF (or other security system) userid under which that connection may run. Though the exit is only called once per a connection, its results are cached and used for every request received on that connection.
- The handler then gives the socket, and starts the RPC/language request.
- If the RPC/language request has not started in the specified time-frame (controlled via a configuration parameter), the handler takes the socket back, issues an error message, and waits for the next request.
- During TDFREE, the RPC/language transaction signals the handler that it is giving back the socket. The handler takes the socket back and waits for the next request.
- When the client closes the socket, the handler frees all associated control blocks and closes the socket.
Prior to the installation and configuration of Mainframe Connect, the CICS region must already have the CICS sockets installed. Briefly, the steps to install CICS sockets are:
- Add hlq.SEZATCP to the DFHRPL concatenation.
- Add a DD entry for SYSTCPD.
- Add TCP RDO entries (located in hlq.SEZAINST(EACICCT).
- Create the EZACONFG dataset to hold the sockets configuration.
Chapter 2 of the z/OS Communications Server IP CICS SOCKETS GUIDE fully explains the installation process and should be carefully read prior to making changes to your CICS region.
Once the CICS Sockets interface is installed in the CICS region, the installation of OSC can proceed. The installation jobs created by the MFC Installer as described in the Sybase MFC Server Option for CICS Installation and Administration Guide.
The base OSC installation defines one listener transaction “SY01”. Configuration data for this listener must be added to the EZACONFG dataset. This may be done either online through the CICS Sockets configuration transaction “EZAC” or using the batch configuration utility “EZACICD”.
Here is a sample EZACICD entry for the Sybase listener:
EZACICD TYPE=LISTENER, Create Listener Record X
APPLID=CICSDEV1 APPLID of CICS X
TRANID=SY01, Use transaction ID X
PORT=3044, Use port number 3044 X
BACKLOG=40, Set backlog value to 40 X
ACCTIME=30, Set timeout value to 30 seconds X
NUMSOCK=100, Support 99 concurrent connections X
IMMED=YES Start listener immediately
Note: The EZACICD utility deletes and recreates the entire EZACONFG dataset! Do not use this utility unless your input includes all entries you wish to have in the dataset. If using the new ESD6 Gatewayless Handler, change the TRANID parameter appropriately.
Multiple Sybase listeners may be defined in a single region. Each listener must have its own unique transaction ID (a requirement of the Sockets Interface). Sybase suggests that additional listener transaction IDs follow the format of SYxx (ie: SY02, SY03, etc.). Remember to copy the RDO entry for SY01, changing the transaction ID appropriately.
After defining the listener to the Sockets Interface, run hlq.OCS150.CICS.JCL(IxTPSEC) to define the additional Sybase listener configuration parameters.
The CICS Sockets Interface must be stopped and restarted to define a new listener. The commands using the CICS Sockets EZAO control transaction are:
EZA0 STOP CICS
EZA0 START CICS
The Sockets Interface only has to be stopped when defining/removing listeners. Once a listener has been defined, any configuration changes made require stopping/restarting only the affected listener:
EZAO STOP LISTENER(SYxx) EZAO START LISTENER(SYxx)
For the legacy (pre-ESD6) gatewayless handler, the default listener transaction id is
“SY01”, with a program id of “SYBLSTNR”. The gatewayless handler transaction id is
“SYSH” with a program id of “SYGWSKTH”.
Under the new ESD6 handler, the default transaction id for the listener is “SYA1”, with a program id of “SYBLIST”. The gatewayless handler uses transaction id “SYZ1” with a program id of “SYBSOCKH”. The Gatewayless Handler transaction (SYZ1) definition requires a TWA size of 200 bytes as well as an intrapartition transient data queue of the same name as the handler transaction id. This is allows the installation of ESD6 without creating a sudden processing change to gatewayless transactions, as well as the ability to have multiple listeners with both the legacy and new ESD6 Gatewayless Handler.
The I2RDO installation JCL member for OSC has been updated to include the new definitions for SYBLIST, SYBSOCKH, SYA1, SYZ1, and TD Queue SYZ1.
The Sybase listener uses a mixture of configuration parameters contained within the CICS Sockets EZAC configuration transaction, as well as Sybase specific parameters contained within the SYBTPSEC configuration module. The new ESD6 Gatewayless Handler also receives parameters from SYBTPSEC.
If using the new ESD6 Gatewayless Handler, SYBTPSEC must be reassembled with the new parameters, using the new version of the SYBTPSEC included with the ESD6 update. SYBTPSEC does not have to be reassembled when continuing to use only the legacy handler. Note: If plans are to have dual listeners, one using the ESD6 handler, and one with the legacy, two SYBTPSEC modules (under different names) must be assembled since different handler transactions must be specified.
EZAC listener parameters used by the Sybase listener:
- ACCTIME – The amount of time (in seconds) the listener will wait on its ECB before initiating its loop. Since any socket activity posts the ECB, this value will not have any effect, except in these cases:
- Shutdown – When the listener is being shutdown, CICS Sockets posts a control bit (checked by the listener) so that it may shut itself down in an orderly fashion. The listener MUST enter its loop in order to check this bit.
- SCHECK – When the “SCHECK” feature (see below) is in use, the listener checks all untaken sockets at the end of its loop.
- APPLID – The APPLID of the CICS region where the listener is residing.
- TRANID – The listener’s transaction ID. It is suggested that Sybase listeners use a transaction ID such as SYxx (SY01, SY02, etc.). When using the new ESD6 Gatewayless handler it’s suggested to use “SYAx” as the listener transaction ID (SYA1, SYA2, etc.)
- PORT – The port number the listener will be using.
- BACKLOG – The number of connection requests allowed to wait on the listener before TCP starts sending “Connection Refused” messages. See the “Tuning” section of this document for additional information. NUMSOCK – The maximum size of the listener’s socket pool. See the “Tuning” section of this document for additional information.
- SECEXIT – The Sybase configuration module created by the SYBTPSEC macro. More information on SYBTPSEC below.
- GWTRAN – The transaction ID of the Sybase Gateway Handler used for connections originating from a Sybase Direct Connect gateway. Defaults to “SYGH”.
- GWLTRAN – The transaction ID of the Sybase Socket Handler used for gatewayless connections. Defaults to “SYSH”. With the new Gatewayless Handler, only the first three characters of this parameter are used, the forth being taken from the listener transaction id. If “GWLTRAN” is set to “SYZ” or “SYZx”, the actual transaction ID called will be “SYZ1” if the listener transaction ID is set to “SYA1”. An intrapartition data queue must also be established using the same transaction ID of the ESD6 handler. This would also be “SYZ1” in the above example. The supplied RDO configuration has been updated to provide new program id’s “SYBLIST, SYBSOCKH”, transaction id’s “SYA1 and SYZ1”, and intrapartition queue “SYZ1”.
- SECURITY – Security mode for this listener. May be set as follows:
- Y – Userids and passwords are checked. Errors are returned to gatewayless transactions at the time of the RPC request, mirroring the sequence of events from gatewayed connections. o H – Userids and passwords are checked. If it is a gatewayless connection, the error is returned immediately and the connection closed (the same behavior as connecting to ASE). Gatewayed transactions treat “H” the same as “Y”.
- N – No userid or password checking occurs.
- U – Userids are checked, but passwords are ignored. This is the recommended setting when using the new ESD6 Gatewayless Handler user security exit.
- T – Use terminal security. The new Gatewayless Handler does not support terminal security. This setting in conjunction with the new handler will provide unpredictable results.
- TERMON – Sign-on transaction when using terminal security. Defaults to SYSO.
- TERMOFF – Sign-off transaction when using terminal security. Defaults to SYSF.
- PING – SYBPING transaction. Defaults to SYPG.
- PWTRAN – Password change transaction. Defaults to SYPM.
- SO_RCVBUF – Overrides the TCP/IP system default for the maximum size of the receive buffer. A value of “-1” indicates that the system default should be used. Defaults to “-1”. See the “Tuning” section of this document for additional information.
- SO_SNDBUF – Overrides the TCP/IP system default for the maximum size of the send buffer. A value of “-1” indicates that the system default should be used. Defaults to “-1”. See the “Tuning” section of this document for additional information.
- TCP_NODELAY – Overrides the TCP/IP system default for the Nagel Algorithm. A value of “1” turns Nagel off. A value of “0” turns it on.
A value of“-1” indicates that the system default should be used. The default is “-1”. See the “Tuning” section of this document for additional information.
- TRACE – A value of “Y” turns on the listener trace messages. A value of “N” turns them off. Defaults to “N”.
- MIXEDCASEPW – A value of “N” indicates that the listener should convert all incoming passwords to upper case. A value of “Y” will leave the passwords in mixed case. MIXEDCASEPW should never be set to “Y” unless the security manager is set to utilize mixed case passwords. Defaults to “N”.
- STRTCHK – The listener MUST be able start the handler transactions (socket or gateway, depending if the incoming transaction is in gatewayless or gatewayed mode) in order for the application RPC transaction to be started. Due to the nature of the interface between CICS and the external security manager (such as RACF), there are some instances where the handler transaction will be unable to start (such as when the RACF “APPL” class is being used). CICS provides no way in which the listener may detect the “non-start” of the transaction. Since the listener knows when the transaction has started (as it is aware that the socket was “taken”), STRTCHK will compare each non-taken socket against an elapsed time interval. If it has not been taken in the number of seconds specified by STRTCHK, the listener will recover the socket, send an error message, and close the socket. This will prevent sockets from “hanging” and causing problems with client applications. Since this feature decreases the efficiency of the listener it may be left inactive. A value of “-1” leaves the STRTCHK feature off. Defaults to “-1”.
- USERID – The userid provided in this field will be used for all transactions originating through this listener, regardless of what is contained within the client request. No validation or password checking is performed. The default is eight blanks (“ “) which indicates that the client’s userid should NOT be overridden.
- DCSERVNAME – A value of “Y” indicates that support for the Direct Connect “sendservicename” is active. The “sendservicename” (added to Direct Connect in 15.0, ESD 7) causes RPC’s to be run using the service name as the mainframe userid. RPC applications may still access the actual client userid via the OSC api. The Direct Connect service name must be an active, valid userid on the mainframe. No validation is performed. A value of “N” (the default) turns off support. If “DCSERVNAME” is set to “N”, requests from Direct Connect servers with “sendservicename” active will be rejected, returning message: “33809 SECURITY ERROR: CANNOT PROCESS DC SERVICE NAME.”
The following parameters are for use with the new ESD6 Gatewayless Handler:
- GWLPOOL – The size of the Gatewayless Handler socket pool. This is the maximum number of sockets that the Gatewayless Handler can manage. Defaults to 50.
- GWLTASK – The maximum wait time allowed by the handler until a started RPC/language request takes the socket. Defaults to 30.
- GWLTIME - The maximum amount of time allowed by the handler before it assumes that an RPC/language request has abended. Note: this is the total amount of time allowed for the entire transaction. So, if it is desired that a transaction is assumed “dead” 30 seconds after start, and GWLTASK=30, then TWLTIME should be set to 60. Defaults to 30.
- GWLEXIT – The name of the user security exit. Leave this parameter blank if a security exit is not provided. See the section below on how to code a user security exit. Defaults to blanks.
- GWLTRACE – Set this to “Y” to write a trace to the CSMT log of activities within the Gatewayless Handler. This is primarily used by Customer Support to help debug issues. Defaults to “N”.
- GWLHANDCHK – The time interval between the last Gatewayless Handler timestamp before the listener verifies if the handler is still running. If the handler is not running, the listener will restart it. A value of “-1” turns off this feature. Defaults to 30. See the section below on handler monitoring and restart.
- GWLMAX (currently defaulting to 10). The purpose of the parameter is to set an upper limit on the number of connections to allow the handler to maintain. This is to allow further control of resources (such as memory) used by the handler. Development felt it was needed to limit the number of connections at some point under the size of the socket pool, since there are conditions (such as the RPC failing to start) where the handler needs to take a socket back. That means for a brief period a connection might have two sockets assigned to it.
A single “SYBTPSEC” module may be used for multiple listeners using the same configuration parameters. Multiple SYBTPSEC modules may be created (under different names) and assigned to various listeners as needs dictate. Each SYBTPSEC module must have a RDO program entry. The supplied entry for SYBTPSEC may be copied and renamed as required.
Gatewayless Handler Monitoring and Restart –
Since the Gatewayless Handler uses shared storage, there are conditions (such as storage violations by other transactions) that may cause the handler to abend. This has not been an issue with legacy handlers since a new handler transaction was always started by the listener at connect time. Should the new ESD6 handler abend, and not be restarted, connections will still be processed by the listener, but the associated requests will never be read.
In order to prevent this situation, the ESD6 handler updates a timestamp in storage shared with the listener. The configuration parameter “GWLHANDCHK” tells the listener what is the acceptable limit between the current time and the last update of the timestamp by the handler. Should this be exceeded, the listener will check to see if the handler transaction is still running. If not, it will restart the handler.
This value is checked whenever the listener sends a new connection to the handler. Therefore, should the handler abend, it will not be restarted until a new connection is dispatched by the listener.
Terminal Security –
NOTE – This feature is being retired and is not supported by the new ESD6 Gatewayless Handler.
Terminal Security (SECURITY=T) is intended for older transactions written for CICS/ESA version 3.1 or earlier. Prior to CICS/ESA, there was no means to check user/password/transaction security without the transaction being tied to a specific terminal. Terminal security involves creating several “dummy” terminals in the DFHTCT table. The listener assigns an incoming connection to one of these “terminals”, signs it on, and then processes normally. The “terminal” is then signed off when the connection is terminated. The following steps are used to activate terminal security:
- Create DFHTCT entries to supply the terminal entries. More terminals than simultaneous connections should be supplied. A sample entry for terminal ID
“SYT1” would look like:
- Add “dummy” DD statements to the CICS region’s startup JCL. A typical statement for the above definition would look like:
//TCPSYT1 DD DUMMY
- Assemble the SYGWTERM table using the above terminal ids. JCL for this table is in hlq.OSC150.CICS.JCL, member OxTERM.
- Set the SYBTPSEC “SECURITY” parameter to “T”.
Terminal Security places a large amount of overhead into the MFC processing flow. Because of this, it is strongly urged not to be used unless absolutely necessary. If it must be used, Sybase engineers suggest that an additional listener be defined for use for connecting/executing transactions that MUST use terminal security, with the other listener(s) used for “normal” security.
User Security Exit -
The purpose of this exit is to allow special mapping from the client userid to an actual RACF (or other security provider) userid. It is up to the user supplied exit to validate if a client userid and password is correct, and to supply the RACF userid that the connection should use.
The exit may be any user supplied program that is written using the CICS API. The handler calls the exit via “EXEC CICS CALL PROGRAM” and passes a
DFHCOMMAREA to specify calling and return parameters. The layout of the DFHCOMMAREA is:
Exit return code.
0 = login accepted
4 = login accepted – display message.
12 = login rejected – display message
16 = login rejected, userexit error
Message to display when return code = 4 or 12.
Userid returned to use on EXEC START command.
Optional data to pass to exit.
Optional data to pass to exit.
Listener tuning tasks can be divided into three interdependent areas: Transaction Flow, Connection/Socket Flow, and Data Transfer Flow.
- Transaction Flow Valid for the pre ESD6 Gatewayless Handler only. –
Since the listener passes sockets off to the Sybase Socket Handler, and then to the actual RPC transaction, it’s important that the CICS region is tuned to allow a smooth flow of OSC transactions. Assuming that the CICS max task (MXT) DFHSIT parameter has been set for optimum performance in the region, two TRANCLASSes should be set up, one for all RPC transactions, and one for the Socket Handler transaction (SYSH). The RPC tranclass should be set to the number of Sybase RPC’s wished to have active at any time, and the SYSH tranclass should be set to the number of gatewayless connections supported at any given time. The SYSH tranclass is unneeded if only gatewayed connections are used.
Gatewayless connections need two tranclasses since each connection has its own SYSH transaction running during the life of the transaction. The SYSH transaction acts as an “anchor” for the TCP/IP socket and is responsible for looking up the RPC name in the SYRPFIL and converting it to the actual tranid. If SYSH were lumped into the same group as the RPC transactions, one undesirable result might be that the tranclass could be full of SYSH transactions, waiting on RPC transactions which would never start.
- Connection/Socket Flow –
The two configuration parameters affecting the connection/socket flow is NUMSOCK and BACKLOG.
The NUMSOCK parameter controls the number of sockets in the listener’s socket pool. These sockets are used for connections waiting on the client to send the login (userid and password) data or CICS to allow the Gateway Handler or Socket Handler transactions to start. If too small a pool is defined, TCP/IP will start rejecting requests (ie: Connection Refused) or CICS will not be running the optimum amount of RPC transactions while waiting for the listener to process requests. If too large a pool is defined, there will be a large number of connections waiting for CICS to start their Gateway Handler or Socket Handler transactions to start. This can cause connections to timeout, based on the CS_LOGIN_TIMEOUT Sybase Open Client parameter set by the client.
The BACKLOG parameter controls the number of connect requests queued to wait on the Listener to accept them. A listener can only accept connection requests one at a time. When the backlog setting is exceeded, “connection refused” messages will occur. Again, if a client waiting in the backlog queue too long could have its CS_LOGIN_TIMEOUT parameter exceeded. Assuming the CICS region can handle the load, multiple Sybase listeners can be defined for the region, reducing the need for large socket pools and backlog settings. Remember that the CICS TRANCLASS settings must be able to handle the combined flow from all of the listeners!
- Data Transfer Flow –
Data transfer is dependent on the speed of the underlying network as well as packet sizes. While MFC can do nothing to control the network hardware, it is able to control the size of the data packets.
The data packet size can be set by the client with the Sybase Open Client CS_PACKETSIZE parameter. The value of this parameter is used by both the client and server applications to control how much data may go into the buffer prior to issuing a write to TCP/IP. However, IBM TCP/IP implemented under z/OS controls the physical packet size. If these are set larger than CS_PACKETSIZE, the TCP packets will size based on CS_PACKETSIZE. But, if the physical packet size is smaller than CS_PACKETSIZE, the actual packet size will be based on the physical packet size.
The physical packet size may be set through SYBTPSEC parameters SO_RCVBUF and SO_SNDBUF. These settings override the z/OS system defaults for any connections accepted through that listener. SO_RCVBUF controls the packet size for incoming (to the mainframe) transmissions, SO_SNDBUF controls the outgoing (from the mainframe) transmissions. Optimum packet sizes are dependent on the amount of data received/transmitted by an individual transaction.
Finally, data transmission is controlled by the “Nagel Algorithm”. This algorithm, created during the early days of TCP/IP attempted to reduce the amount of data collisions by adding an arbitrary wait between receives and sends. This can be disabled by setting the SYBTPSEC TCP_NODELAY to “1”.