TCP/IP API Support › Generic Listener Service › Implementation

Implementation

Generic listening is a service provided by the SOCKET line driver. The parameters that control the listener service are defined using the following methods:

• A listener PTERM: it defines the port on which to listen, the backlog, the task code to invoke when a connection is established and the mode in which to invoke the task. Optionally, if running on a multi-homed host, the TCP/IP stack can be selected. Also optionally, a character string can be defined to pass to the attached task.
• A task and associated program definition.

  Note: The task and program should be defined to the security system so that anyone can execute them.

The program associated with the server task receives control with a parameter list containing the following addresses:

• The address of an 80-byte character string set to the value of the string specified in the listener PTERM definition or blanks if none was specified.
• The address of the socket descriptor.
• The address of a 4-byte field named the resume counter. The resume counter is provided for suspend/resume processing.

Notes:

• If the listener program is written in CA ADS the parameters are passed in the SOCKET-LISTENER-PARMS record. This record must be included as work record in the dialog definition.
• If MODE IS SYSTEM is specified in the LISTENER PTERM definition, the listener program must be written using DC/UCF calling convention conventions as described in CA IDMS System Operations Guide.

The program associated with the server task responds to the message sent from the client application. In addition to performing the required business function, it is also responsible for the following services:

• Security—When the program receives control, no user has been signed onto the system. For security purposes, the executing program must immediately signon to the system. To provide signon capabilities you must link to the RHDCSNON program. Or, for Assembler programs, you can code a #SECSGON macro.

  More Information:

  For more information about linking to RHDCSNON, see the CA IDMS System Tasks and Operator Commands Guide. For more information about #SECSGON, see the CA IDMS Security Administration Guide.

• Character conversion—If the remote host sends text messages in a character set other than the one used on the central version, these text messages might need translation. The program is responsible for performing this translation and IDMSIN01 functions are provided to assist in this process.
• Closing the socket—Once the conversation is over, the socket should be closed. Closing the socket causes a sign off when the task terminates. If the task ends normally without closing the socket, generic listening starts a "receive" on the socket because it interprets this situation as a suspend. As a result, the LTERM/PTERM pair remains in use and long-term resources, such as the signon element, remain allocated. These resources are subject to CA IDMS time-out processing and can be deleted with the DCMT VARY LTERM ... RESOURCE DELETE command.

  Note: If the task abends, CA IDMS closes the socket and the PTERM/LTERMpair is signed off automatically.

More Information:

For more information about implementing the generic listening service required for TCP/IP integration, see the CA IDMS System Generation Guide.