> For the complete documentation index, see [llms.txt](https://docs.editran.onesait.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.editran.onesait.com/documentacion-editran/ibm-editran-v5.3-cics-en/tcp/summary-operation-definitions-clarifications.md). # Summary: Operation, definitions, clarifications ## Relationships between the necessary parameterizations * TCP STARTUP PROCEDURE ``` //TCPIPROC JOB MSGLEVEL=1 //STARTING EXEC TCPIPROC XXPROFILE DD DSN=SW.TCPIP.SEZAPARM(CPUBPROF),DISP=SHR XXSYSTCPD DD DSN=SW.TCPIP.SEZAPARM(TCPDATAB),DISP=SHR ``` * PROFILE file (SW\.TCPIP.SEZAPARM(CPUBPROF)) ``` PORT 7777 TCP CICSSITD ; CICS Socket KEEPALIVEOPTIONS INTERVAL 2 ENDKEEPALIVEOPTIONS DEVICE LOSAB4 LCS 1002 LINK OSAB4TCP IBMTR 0 LOSAB4 HOME 192.168.172.088 OSAB4TCP GATEWAY 192.168.172 = OSAB4TCP 1500 0 BUFFER PARAMETERS. (DATABUFFERPOOLSIZE in 2.4 and TCPSENDBUFFERSIZE-TCPRECEIVEBUFFERSIZE in later versions) ``` * TCPDATA file (SW\.TCPIP.SEZAPARM(TCPDATAB)) ``` TCPIPJOBNAME TCPIPB NSINTERADDR 172.29.2.41 NSINTERADDR 192.168.1.30 NSPORTADDR 53 ``` * CICS STARTUP ``` //DFHRPL // DD DSN=TCPIP.SEZATCP,DISP=SHR ---------------------------------------------------------------------- //ZTB1INTR DD SYSOUT=(A,INTRDR) //******************************************************************** //TCPCICS DD SYSOUT=H,DCB=(DSORG=PS,RECFM=V,BLKSIZE=136) //SYSTCPD DD DSN=SW.TCPIP.SEZAPARM(TCPDATAB),DISP=SHR //******************************************************************** ``` * DCT TABLE ``` DFHDCT TYPE=SDSCI, X DSCNAME=TCPCICS, X DFHDCT TYPE=EXTRA, X DESTID=TCPI, X DSCNAME=TCPCICS ``` * PLT TABLE ``` Entries in the PLTPI after DFHDELIM: DFHPLT TYPE=ENTRY,PROGRAM=EZACIC20 DFHPLT TYPE=ENTRY,PROGRAM=ZTBPOTCI Entries in the PLTSD before DFHDELIM: DFHPLT TYPE=ENTRY,PROGRAM=EZACIC20 DFHPLT TYPE=ENTRY,PROGRAM=ZTBPOTCF ``` * CONFIGURATION FILE (EZACONFG). ``` EZAC,DEFINE CICS APPLID ===> CICSSITD TCPADDR ===> TCPIPB ERRORTD ===> TCPI EZAC,DEFINE,LISTENER APPLID ===> CICSSITD TRANID ===> ZTBA PORT ===> 07777 SECEXIT ===> EDITRAN ``` * Editran (LOCAL ENVIRONMENT) ``` TCP API ..: ZTBB TCP PLTINIT: ZTBZ | TCP/IP FIELDS: TCPNAME...: TCPIPB | | USER DATA TIME-OUT MAX(MSS)..: 020 NO. OF SIMULTANEOUS LISTENER CONNECTIONS....: 020 | | USE DNS SERVER IN INCOMING CALLS..: N SEND TIME IN MILLISECONDS (001-999)..: 100 | | TCP-PX SEND BUFFER (LISTENER).: 000000 | | TCP-PX RECEIVE BUFFER (LISTENER).: 000000 | ``` * Editran (TRANSMISSION SESSION) ALLOWED CONNECTION TYPES: I ``` | TCP SEND BUFFER: 000000 | | TCP RECEIVE BUFFER: 000000 | ``` ## Description of necessary parameterizations 1. The TCP startup procedure starts a TCP stack and has 2 files: * PROFILE file. The following are assigned in it: * Ports (PORT). It is not mandatory to do so. If it is coded, that port will be permanently assigned to a CICS for all IP addresses of the stack; that is, all incoming calls that arrive through that stack and that port will be passed to the CICS coded in that macro. In CICS, there must be a record in the EZACONFG file containing an Editran transaction ID (ZTBA) assigned to that port. If it is not coded, the described record will exist in CICS, but it cannot be assigned to a port that we reserve for something else; that is, if for example we reserve port 23 for TELNET, in CICS that port cannot be assigned to transaction ZTBA. If we want to connect 2 teleprocessing monitors to the same stack, and we code the PORT macro, we will not be able to receive calls through that port from the monitor that has not been assigned to the macro. * KEEPALIVE parameter. It is advisable to set it low (2-3 minutes) so that it notifies editran in the event of connection drops that are not reported by TCP. Editran, for its part, includes a SETSOCKOPT function related to this parameter. * Local addresses of the stack. In the example, an OSA card has been introduced. To do this, a LINK macro is coded with its name. Next, the OSA is associated in the HOME macro with its local IP address. Finally, a GATEWAY macro is included to specify the routes used for outgoing calls. If we have 2 IP addresses, we would therefore have 2 OSA and 2 LINK macros. Outgoing calls in this case could be limited to just one. It is the system administrator's job to define access routes according to their needs, especially in security matters. * Stack buffer size. The send and receive sizes are specified together. It is the administrator's responsibility to distribute them correctly for the proper functioning of editran. * TCPDATA file. The following are assigned in it: * The addresses of the name servers (NSINTERADDR parameter). If a connection request is generated from CICS for an editran session whose IP addresses are DNS, these must be resolved as real IP addresses. To do this, calls are made to the different name servers that we code. The address of these servers is what is coded here. If the requested DNS exists there, they will therefore return the IP address to which the connect must be made. * Their port (NSPORTADDR parameter) * The name of the TCP address space in the stack (TCPIPJOBNAME). That name must match the BPXPRMXX member (XX is the suffix) of SYS1.PARMLIB and the TCPNAME parameter on the second editran environment screen. 2. CICS startup. The following elements are defined: * TCP libraries that resolve socket calls and contain IBM programs. * DCSNAME of the extra-partition destination table. A DCT with that name will therefore be included. It is used to generate TCP output messages. * An SYSTCPD that points to a TCPDATA FILE (in principle it should be the same one pointed to by the TCP stack procedure). It is used to point to the addresses of the name servers (NSINTERADDR parameter). That TCPDATA does not have to be the one of the stack to which the CICS is associated. Calls to this SYSTCPD are used only for client processes. editran, therefore, will resolve the DNS of the sessions according to the servers contained in the TCPDATA of the SYSTCPD and not according to the TCP startup procedure's TCPDATA, although it is insisted that it could be the same one. 3. DCT table. The DCSNAME described in the CICS startup is defined, as well as the destination used to output the socket interface messages through it. That destination must also be coded in the CICS record of the EZACONFG file, specifically in the ERRORTD parameter. 4. PLT. It is divided into 2 parts: * Startup PLT- Programs are called that activate/deactivate the sockets and the listener. Specifically, the first are activated by the IBM program EZACIC20 and the second by the editran program ZTBPOTCI, which starts transaction ZTBZ (ZTBPOTCZ). From there, reading the EZACONFG will start all listener records found with the SECEXIT = editran parameter. The startup transactions are the TRANID parameter of that record. If we have several listeners (each listening on a different port), all the tranid will be defined in the PCT and all of them will be associated with program ZTBPOTCC. These started listener transactions will remain active, listening for connection indications, each on its own port, until CICS is brought down again or until the sockets for CICS are stopped. If any listener has not been activated at this point, transaction ZTBZ can be invoked to activate it. * Termination PLT. At the moment of a CICS failure, the termination PLT will come into operation. Specifically, the IBM program EZACIC20, which deactivates the sockets for CICS, and then the editran program ZTBPOTCF, which will communicate with the active editran LISTENERs so that the latter can finish in an orderly manner. 5. In the EZACONFG file, the following are defined, (in the example through transaction EZAC): * CICS records. In it, the name of the teleprocessing monitor is associated with the stack it connects to (TCP address space), that is, with the name that appears in the TCPIPJOBNAME of the stack with which the CICS connects (TCPDATA parameter). The DCT destination is also defined (ERRORTD parameter). If CICS records are defined that do not correspond to the teleprocessing monitor we are working with, the EZACONFG must be the same in the defined CICS. * LISTENER records. These are always associated with a specific CICS, that is, we could have 2 identical ones associated with different CICS. They include the editran transaction ID and the port on which it will listen. Therefore, several editran transaction IDs (with different names) can be defined for the same CICS record, but associated with the same program and listening on different ports. The EZACONFG file is defined through JCL and modified via transaction EZAC. 6. PPT. The following programs are defined: ZTBPOTCC (parent server or listener program) ZTBPOTCD (child server or client program) ZTBPOTCZ (program that will start the different copies of ZTBPOTCC according to the transactions defined with them), ZTBPO201 (editran core for TCP connections), ZTBPOTCI (startup PLT) ZTBPOTCF (termination PLT) and IBM programs. 7. PCT. The following are defined: ZTBB (program ZTBPOTCD) (coded in editran environment as TRANSID API TCP), ZTBZ (program ZTBPOTCZ), ZTBA or XXXX (program ZTBPOTCC) and IBM transactions (EZAC, EZAO and those required). ## Practical example and conclusions A very complex example has been sought in order to find the necessary relationships and verify the points of incorrect operation, so its implementation is not recommended.
1. We have 2 TCP STACKS (STACK001 AND STACK002) with the following characteristics: * STACK001 has a startup procedure that uses a PROFILE001 and a TCPDATA001. * PROFILE001 has PORT 7777 against CICS002 and a home with the addresses 111.111.111.111 associated with an OSA11 and 111.111.111.112, associated with an OSA12 * TCPDATA001 has a TCPIPJOBNAME TCPIP001 and no NSINTERADDR * STACK002 has a startup procedure that uses a PROFILE002 and a TCPDATA002. * PROFILE002 has no PORT and has a home with the address 222.222.222.222 associated with the OSA21 * TCPDATA002 has a TCPIPJOBNAME TCPIP002, an NSINTERADDR 002.002.002.002 and another NSINERADDR 002.002.002.001. 2. We have 2 CICS (CICS001 AND CICS002) with the following characteristics: * CICS001. On startup it points to TCPDATA002. * CICS002. On startup it points to TCPDATA002. 3. We have 1 or 2 configuration files (EZACONFG). In the example, 2 are defined: CONFG001 for CICS001 and CONFG002 for CICS002) with the following characteristics (all transactions are associated with program ZTBPOTCC): * CONFG001: A CICS record APPLID= CICS001, TCPADDR=TCPIP001 * CONFG001: A CICS record APPLID= CICS001, TRANID=ZTBQ, PORT =7777 * CONFG001: A CICS record APPLID= CICS001, TRANID=ZTBR, PORT =7778 * CONFG001: A CICS record APPLID= CICS001, TRANID=ZTBS, PORT =7779 * CONFG001: A CICS record APPLID= CICS001, TRANID=ZTBY, PORT =7779 * CONFG002: A CICS record APPLID= CICS002, TCPADDR=TCPIP002 * CONFG002: A CICS record APPLID= CICS002, TRANID=ZTBQ, PORT =7777 * CONFG002: A CICS record APPLID=CICS002, TRANID=ZTBR, PORT =7778 * CONFG002: A CICS record APPLID= CICS002, TRANID=ZTBT, PORT =7779 4. We have 2 editran: * EDICICS001. In the TCPNAME environment it points to TCPIP002 and in TCP API to ZTBB. * EDICICS002. In the TCPNAME environment it points to TCPIP001 and in TCP API to ZTBB. If the listeners are started on both CICS (PLT, transaction ZTBZ or transaction EZAO start LISTENER), as long as the sockets for cics have been started, the following processes will be attached: 1. The ZTBQ transaction of CICS001 should remain listening for incoming calls on port 7777 of addresses 111.111.111.111 and 111.111.111.112, since the CICS record in EZACONFG specified TCPIP001, and therefore it uses STACK001, which has TCPIPJOBNAME = TCPIP001 in its TCPDATA001, taking the local address from the HOME macro of PROFILE001. However, since in that STACK001 the PROFILE001 specifies PORT 7777 assigned to CICS002, it will not be possible to activate the described LISTENER, since it is assigned to another CICS (ERRNO 13 or permission denied). If a remote system calls that address and port, it will give a connect 61 error (no active LISTENER exists) 2. The ZTBR transaction of CICS001 connects correctly to port 7778 of address 111.111.111.111 and 111.111.111.112 3. The ZTBS transaction of CICS001 connects correctly to port 7779 of address 111.111.111.111 and 111.111.111.112 4. The ZTBY transaction of CICS001 does NOT connect correctly to port 7779 of the previous addresses, since ZTBS of CICS001 already has it. It returns errno 48 (another process already has it taken) 5. The ZTBQ transaction of CICS002 connects correctly to port 7777 of address 222.222.222.222. 6. The ZTBR transaction of CICS002 connects correctly to port 7778 of address 222.222.222.222. (CICS001 is connected through its ZTBR to the same port of addresses 111.111.111.111 and 111.111.111.112). 7. The ZTBT transaction of CICS002 connects correctly to port 7779 of address 222.222.222.222 (CICS001 is connected through its ZTBS to the same port of addresses 111.111.111.111 and 111.111.111.112). 8. The listeners of both CICS, although at EZACONFG level they have a TCPADDR that does not match the TCPNAME of the editran environment, will work correctly, even though editran uses the TCPNAME ENVIRONMENT parameter in the INITAPI macro. However, the TCPIP interface currently ignores it. This does not happen in the IMS teleprocessing monitor, in which case the interface faithfully follows what is indicated in editran. In that monitor there is no EZACONFG file, so the relationship is made between the TCPIPJOBNAME and the editran environment parameter. At this point, we will have: 1. CICS001. It has 2 editran listeners, which listen to incoming calls that reach it through addresses 111.111.111.111 and 111.111.111.112. These listeners are: * ZTBR. It only handles incoming calls through those addresses and port 7778. * ZTBS. It only handles incoming calls through those addresses and port 7779. 2. CICS002. It has 3 editran listeners, which listen to incoming calls that reach it through address 222.222.222.222. These listeners are: * ZTBQ. It only handles incoming calls through that address and port 7777. * ZTBR. It only handles incoming calls through that address and port 7778. * ZTBT. It only handles incoming calls through that address and port 7779. These listeners will remain started until CICS goes down or until the sockets for cics go down. When any call comes in through one of the described addresses and ports, the associated transactions will accept the call and hand control over to ZTBB (CHILD SERVER TRANSACTION) so that it is the one in contact with the editran core and with the remote ends, so the listener transactions remain only waiting for new connection indications. Thus, for example, if 6 calls enter CICS001, 2 of them through address 111.111.111.111 port 7778, another 2 through address 111.111.111.112 port 7778, and another 2 through address 111.111.111.111 port 7779, at least 8 tasks will be running (ZTBR, ZTBS and 6 ZTBB). The ZTBB end when the connection between both ends is released. In turn, the ZTBB transaction is also the editran CLIENT transaction, so that if 10 outgoing calls had been made from CICS at this point, 18 tasks would be running (the previous ones plus another 10 ZTBB). In the client process, the editran environment TCPNAME will also be used for the INITAPI macro, but as explained above, it ignores that value and connects to what has been coded in the TCPADDR of the EZACONFG CICS record. Other actions that could occur are: 1. If in editran of CICS001 a remote is defined with a DNS and not with an IP address, and an attempt is made to generate a call request from CICS, it is resolved correctly because, although that CICS is associated with STACK001 (which has no NSINTERADDR in TCPDATA001), at the startup of that CICS it was indicated that it should use TCPDATA002 for this type of situation. If TCPDATA001 had been selected at startup, DNS resolution would not have been possible because there is no name server. If the server that resolves the DNS is 002.002.002.001, 2 calls will have been made to 2 name servers (first to the one associated with address 002.002.002.002 and then to the one that resolves 002.002.002.001) 2. A teleprocessing monitor cannot be connected to 2 TCP stacks at the same time. 3. Two teleprocessing monitors can coexist with the same TCP stack, but they cannot simultaneously start two listeners on the same port. This is the same as starting 2 different transactions on the same port within a teleprocessing monitor. It is also the same as trying to start the same listener twice, in which case the editran program itself will not allow it, although the sockets interface would not allow it either because another one already exists on the same port. It is also not possible for a CICS to be a server on one STACK and a client on another. 4. In server actions, the local IP address is not used in the BIND macro, so a listener would end up listening on one port for all the IP addresses of a startup stack (ADDRESS 00000000 of PORT XXXXX). VIPAs (Virtual IP addresses) can also be included in the stack. However, there does not seem to be much use in having a VIPA or an OSA listen on one port and another VIPA-OSA listen on a different one. The implemented solution is that both listen on both ports. In the router that has access to the host, the VIPA would have to be coded with a static address. 5. The EZACONFG file CAN be unique and can be updated (transaction EZAC) from a SINGLE CICS, since the key includes the NAME of the teleprocessing monitor. In this case, it must be seen with the same DSN by the other CICS. However, it is not possible to start-stop the sockets for cics or the LISTENERs of another CICS that is not the local one, that is, we will be able to define in the EZACONFG of CICS001 the CICS002 (CICS key) and the LISTENERs of CICS002 (in this latter CICS the same EZACONFG as in CICS001 would be defined), but we would not be able to activate from CICS001 the sockets for CICS nor the LISTENERs of CICS002. These are activated from CICS002 with transaction EZAO. 6. If we want to assign another STACK, without stopping CICS, we would stop the LISTENERs with EZAO STOP CICS (the listeners give error 10300 in the editran log), so with this command the sockets for cics are also stopped. Next, we modify the corresponding CICS record with EZAC ALTER CICS, putting in the TCPADDR parameter the name of the TCP address space in the new stack. After this, we would activate the sockets for cics (EZAO START CICS) and FINALLY we would activate the listeners (EZAO START LISTENER or by running ZTBZ). If error 121 occurs in the MACRO takesocket, it may mean that a call has come in and that the main listener (ZTBA or others) has started the child listener (ZTBB) and it has not replied to the former with that macro within the time specified in EZACONFG, GIVTIME parameter. If so, review CICS parameterization, transaction priorities, the EAS parameter in the CICS definition to VTAM and the relationship between the PCT TCLASS parameter and the SIT CMXT (in the SIT there is the MXT parameter indicating the number of CICS transactions), since it may happen that there was not enough time to start the task and this can happen both due to CICS stress and due to parameterizations that limit the number of running tasks. 7. The EAS parameter, in the CICS definition to VTAM, is the number of communication tasks running. In the PCT the task can be assigned to a class (from 01 to 10), with the TCLASS parameter, and in the SIT the CMXT parameter states the number of transactions running in each class and the CMXT to indicate the total number. For TCP, there is at least one permanently running: a listener (until CICS or SOCKETS for CICS goes down), n ZTBB (1 for each established connection, which die when transmission ends) and n ZTB0 (editran cores), which start and die for each message burst (NUM.REG.SINCRONISMO parameter, of the editran session profiles) that is sent-received over each connection. Thus, for example, if we have 4 connections, we will have 1 + 4 + x tasks running simultaneously. If the parameters are not suitable, CICS slows down. ## Considerations on buffer space It is possible to control the size of the send and receive buffers, (to see the definitions, consult the [Utilities and Codes](/documentacion-editran/ibm-editran-v5.3-cics-en/utilities-and-codes.md). As for processing speed, the entity must be the one to limit or correctly adjust the parameterizations. All this is related to the sending burst of each transmission session (number of records sent between each acknowledgment), the speed of the local line, the speed of the remote line, the number of simultaneous processes, the MTU size, the transmission length, etc. Thus, for example, if we connect to a remote to which we are going to emit bursts of 100 messages (of 4050), this implies that we will write about 400 K in the send buffers. If for that session we define TCP send buffer 0, it will take the value that exists in the stack. If there is nothing, it will take the default 16 K and the transmission will probably slow down. If, on the other hand, we had coded 200000 bytes (200 K) in the send buffer of the session, (while we write into the buffer, it keeps draining and leaving new space available), there would probably be no slowdown at all. In the SIT and in the CICS startup definition to VTAM the maximum number of simultaneous tasks is defined. In the previous example there were 18 SIMULTANEOUS tasks and simultaneous cores, editran batch processes, time-out processes, etc. would have to be added. ## TCP/IP buffer traces In some entity, a buffer trace has been obtained, in which the send and receive window can be observed and a buffer utilization calculation can be made. Below, and for informational purposes only (without any support whatsoever from editran), are the steps that said entity followed to obtain that trace (apparently IPCS is required): The OS/390 V2R6.0 eNetwork CS IP Diagnosis manual includes the procedure for "IP Packet Trace". (There is another type of trace called "Component Trace" whose procedure is very similar to this one). The steps to follow are: 1. Start the TCP/IP trace: V TCPIP,proc\_arranque\_TCPIP,CMD=O,DSN=data\_set\_name data\_set\_name : File or library member that must contain the following instructions: ``` PKTTRACE ON PKTTRACE FULL IP=Remote_IP_address ``` 2. Start the external writer. TRACE CT, WTRSTART=TRTCP1, WRAP ``` SYS1.PROCLIB(TRTCP1): This member must contain: //TRTCP1 PROC //IEFPROC EXEC PGM=ITTTRCWR //TRCOUT01 DD DSN=CUALIF1...CUALIFn.TRACETC1, DISP=OLD ``` The trace will remain, unformatted, in the DSN represented by TRCOUT01. 3. Connect the external writer to the TCP/IP stack: ``` TRACE CT, ON, COMP=SYSTCPDA, SUB= (proc_arranque_TCPIP) Reply: R nnn,WTR=TRTCP1,END ``` 4. Reproduce the problem. 5. Disconnect the external writer. ``` TRACE CT, OFF, COMP=SYSTCPDA, SUB= (proc_arranque_TCPIP) Reply: R nnn,WTR=DISCONNECT,END ``` This reply is usually not requested. 6. Stop the external writer. ``` TRACE CT, WTRSTOP=TRTCP1 ``` 7. Stop the TCP/IP trace. ``` V TCPIP,proc_arranque_TCPIP,CMD=O,DSN=data_set_name ``` data\_set\_name: File or library member that must contain the following instructions: ``` PKTTRACE OFF ``` 8. Process the trace data existing in the previous data set and obtain it in another data set, that is: > Create the DATA SET and associate it with the DDNAME IPCSPRNT, that is, from option P.6 of ISPF, execute the following commands exactly as they are: > > * FREE FI (IPCSPRNT) > * ALLOCATE DDNAME (IPCSPRNT) DATASET ('CUALIF1...CUALIFn.PRINT') NEW > > KEEP SPACE (10, 5) TRACKS DSORG (PS) RECFM (V B A) LRECL (125) > > BLKSIZE (1254) > > (The DATA SET name can be any name; the important thing is that it is associated with the DDNAME IPCSPRINT) > > From TSO, access IPCS. > > > Menu 0: Source: DSNAME ('CUALIF1...CUALIFn.TRACETC1') > > > > Message Routing: PRINT TERMINAL > > > > Menu 2.7.1.D: Component: SYSTCPDA > > > > GMT/Local: L > > > > Report Type: FULL > > > > Options: PACKETTRACE > > > > Menu 2.7.1.S. > > > > Exit IPCS. In the IPCSPRNT DATA SET we obtain the formatted trace. > > --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.editran.onesait.com/documentacion-editran/ibm-editran-v5.3-cics-en/tcp/summary-operation-definitions-clarifications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.