Open ServerConnect Programmer's Reference for COBOL

Home

Open ServerConnect Programmer's Reference for COBOL

Chapter 1: Introduction

Chapter 1

Introduction

This chapter includes the following sections:

What Is Open ServerConnect?

Open ServerConnect is a programming environment that lets you create mainframe transactions that Sybase client applications can execute. Open ServerConnect transactions can retrieve and update data stored on an IBM mainframe in any mainframe resource, such as VSAM files, TD queues, TS queues, and DL/1 databases, and in DB2 databases and other DBMSs.

Open ServerConnect is available for CICS, IMS TM and MVS. It runs on an IBM System/390 or plug-compatible mainframe computer. It uses a host transaction processor, such as CICS, as a communications front end and uses the LU 6.2 or TCP/IP communications protocols.

What is Gateway-Library?

Open ServerConnect provides a set of built-in high-level functions for use in mainframe server applications that communicate with Sybase clients such as Open Client applications, third-party tools, and server-to-server programs. These built-in functions are linkable subroutines collectively known as Gateway-Library. Gateway-Library functions are called through a stub in the application program. An Open ServerConnect application program uses a CALL statement to invoke a Gateway-Library function.

You can use Gateway-Library functions with all versions of Open ServerConnect. Minor coding differences exist between CICS and IMS TM. Those differences are discussed in "Differences Between CICS, IMS TM and MVS".

Gateway-Library Functions

Gateway-Library functions provide data conversion and LU 6.2 and TCP/IP communication functions to mainframe application programs. Each Gateway-Library function performs one or more specific task(s) in the communication between a server and a client.

Gateway-Library functions can:

Retrieve and process requests from remote clients or servers
Describe and return results to requesting clients or servers
Manage global and transaction-specific tracing and accounting recording at the mainframe

Open ServerConnect uses the Sybase Tabular Data Stream (TDS) protocol to transmit data between the mainframe server and Sybase clients. LU 6.2 or TCP/IP calls are embedded within Gateway-Library functions. All your application program needs to do to send and receive data streams is to call the appropriate Gateway-Library functions. Because Gateway-Library functions automatically issue the appropriate LU 6.2 or TCP/IP calls, no additional code is needed. You do not need to know the details of TDS or your network protocol to use Gateway-Library functions.

All Gateway-Library functions begin with the letters "TD". For example, the TDINIT function initializes the Gateway-Library environment, and the TDRCVPRM function retrieves the data from a parameter in a call sent by a remote client.

The complete set of Gateway-Library functions is included on the product tapes. The program stubs that load and call the Gateway-Library functions are also included. For a list of all Gateway-Library functions and what they do, see Table 3-1: List of Gateway-Library functions on page 3-1.

Using Client/Server Connections

Open ServerConnect supports both three-tier (gateway-enabled) and two-tier (gateway-less) environments. It can receive requests from LAN clients through any of the following:

Transaction Router Service (TRS) or Net-Gateway using SNA or TCP/IP in a three-tier gateway-enabled environment
TCP/IP in a two-tier gateway-less environment
Adaptive Server Enterprise for server to server communication

If you use SNA as your protocol, use Online Transaction Processing (OLTP), or have large numbers of geographically-dispersed Adaptive Servers, you must use a TRS or Net-Gateway in a three-tier environment for routing.

Note: For detailed information about compatibility, network drivers, new features in this version, performance factors, security, three-tier and two-tier environments and how to install and configure Open ServerConnect in both environments, see the Open ServerConnect Installation and Administration Guide.

SNA Connections

A group of logical connections is defined to SNA by the TRS administrator. Each logical connection connects a mainframe transaction processing region with a remote port on a TRS platform. Every request forwarded from a TRS to a mainframe server uses one of these logical connections to communicate with its remote partner. When a request is sent across a connection, it is called a conversation.

SNA connections are activated when a TRS is started and remain active until the TRS is shut down or deactivated.

TCP/IP Connections

There is no difference in the use of Gateway-Library functions for SNA or TCP/IP networks.

In three-tier environments, the TRS administrator defines a group of TCP/IP communication sessions connecting a mainframe teleprocessing region with a remote port on a TRS. For detailed information about configuring TRS, see the DirectConnect Transaction Router Service User's Guide.

In two-tier environments, LAN clients directly login to Open ServerConnect using TCP/IP for connectivity. For information, see the Open ServerConnect Installation and Administration Guide.

Initializing the Gateway-Library Environment

Each mainframe server application that uses Gateway-Library must initialize the operating environment. Gateway-Library uses two structures to do this: IHANDLE and TDPROC.

The IHANDLE structure is a transaction-wide structure that contains configuration parameters and other high-level information used to set up the operating environment for a Gateway-Library transaction. It is defined for each transaction by TDINIT.

TDINIT must be the first Gateway-Library function call in each application. The IHANDLE structure corresponds to the context handle in Open Client Client-Library(TM).

After the environment is initialized, an application must establish a conversation between the client and the server over one of the predefined connections. In Open ServerConnect, a logical connection is represented by a TDPROC structure. A TDPROC structure is associated with an IHANDLE structure and is defined in TDACCEPT.

The TDPROC structure corresponds to the DBPROCESS structure in DB-Library(TM) and to the connection and command handles in Client-Library. Gateway-Library sends commands to the server and returns query results to the application through the TDPROC structure.

The handle for TDPROC is stored in the argument TDPROC. Every Gateway-Library function that sends or accepts data across a connection must specify that connection handle in its TDPROC argument.

Starting and Ending a Conversation

A conversation is established when a client sends a transaction request and a server accepts the request. It remains open as long as the client and server are communicating about that request. When all results and messages are returned to the client, the program must end the conversation and free up the TDPROC structure. The function TDFREE is included for that purpose. The last Gateway-Library function called by your application must be TDTERM, which frees up any remaining storage.

After returning results to a client, a transaction can either end the communication (short transaction) or wait for another client request (long-running transaction). In long-running transactions, TDSNDDON marks the end of a single request, but does not necessarily end the transaction. To end a transaction, the CONN-OPTIONS argument of TDSNDDON must be set to TDS-ENDRPC. The transaction then calls TDFREE and TDTERM to free up storage. Long-running transactions can be coded under CICS or the IMS TM explicit API.

Handling Client Requests

Gateway-Library functions are designed to be symmetrical. That is, each time a program at one end of a connection issues a sending call, the program at the other end issues a corresponding receiving call.

In Open ServerConnect, the mainframe is always a server, never a client. Therefore, all the functions documented in this manual are those used by a server. Each TDRCVxxx function you code in your server application is responding to a corresponding send function issued by the client or TRS, and that the data you send with a TDSNDxxx function is accepted by a corresponding receive function in the client program.

For example, if the client is an Open ClientConnect program, TDRCVSQL and TDRCVPRM retrieve data sent by the client function CTBSEND, and TDSNDROW returns rows that are retrieved by the client function CTBFETCH.

Note: It is possible to code mixed-mode programs that act as both server and client, using both Gateway-Library and Client-Library functions. To do this, you must have Open ClientConnect installed in the same region as Open ServerConnect.

Processing Client Requests

A client can send the following types of requests to a mainframe server:

RPCs

For each client RPC, the mainframe application programmer must write a corresponding server transaction that executes whenever the client calls that remote procedure.

Language Requests

If you have MainframeConnect for DB2/MVS-CICS installed at the mainframe, you have a prewritten transaction that processes SQL language requests to DB2. This transaction, called AMD2, uses DB2 dynamic SQL to process incoming SQL statements. AMD2 handles all language request processing; no additional code is required.

If you do not have MainframeConnect for DB2/MVS-CICS, or if you want to send language requests to a custom-written language handler, you must write your own language transaction. Gateway-Library includes language-handling functions for this purpose. An example of a program that executes SQL language requests is included on the API tape (SYCCSAL2) and is printed in Appendix C, "Sample Language Application for CICS".

Note: MainframeConnect is available only for MVS-CICS environments. For IMS TM and native MVS environments, use OmniSQL Access Module for DB2 for IMS TM and MVS with the SYRT transaction for processing language requests. Cursors and dynamic SQL are not supported.

Cursor Requests

If MainframeConnect for DB2/MVS-CICS is installed at the mainframe, AMD2 processes cursor requests to DB2.

If MainframeConnect for DB2/MVS-CICS is not installed, you must write a server transaction to process cursor requests from the client. A single server transaction can process multiple cursor requests from the client.

Dynamic SQL Requests

If MainframeConnect for DB2/MVS-CICS is installed at the mainframe, AMD2 processes dynamic requests to DB2.

If MainframeConnect for DB2/MVS-CICS is not installed, you must write a server transaction to process dynamic requests from the client. A single server transaction can process multiple dynamic requests from the client.

Differences Between CICS, IMS TM and MVS

For the most part, the use of Gateway-Library functions in CICS, IMS TM and MVS is the same. The minor differences that exist are discussed in Table 1-1, and noted in the reference pages for the affected functions.

Table 1-1: Coding differences between CICS, IMS TM and MVS
Function
Difference Between CICS, IMS TM and MVS
TDINFRPC
TDSTATUS
The action taken when the communication state (COMM-STATE) is TDS-RESET can differ between CICS, MVS and the IMS TM implicit API:
Under CICS, MVS, and the IMS TM explicit API, the transaction exits as soon as possible.
Under the IMS TM implicit API, the transaction can call TDGETREQ to accept another client request or it can exit.
TDINIT
The first argument differs between CICS and IMS TM:
Under CICS, the communications I/O block, passed as the first parameter in TDINIT, is the EIB (DFHEIBLK).
Under IMS TM, the first TDINIT parameter is I/O PCB (IO-PCB).
Under MVS, a null pointer should be used.
TDSETPT
Used with IMS TM only, to indicate the type of IMS TM transaction.
TDSNDDON
Value of CONN-OPTIONS in CICS, MVS, and the IMS TM explicit API can be set to TDS-ENDREPLY in long-running transactions. TDS-ENDREPLY cannot be used under the IMS TM implicit API. To learn how to simulate long-running transactions in the implicit API, see "Long-Running Transactions".
TDINFACT
TDSETACT
Accounting records are written to different logs under CICS, IMS TM and MVS:
Under CICS, accounting functions use VSAM files as log files. The default file name is SYTACCT1.
Under IMS TM, accounting functions use the IMS TM log.
Under MVS, the records are written to a sequential file. The DDNAME of this file is specified as a parameter in TDCUSTOM (MVSDDNAME).
TDINFLOG
TDINFSPT
TDLSTSPT
TDSETLOG
TDSETSPT
TDWRTLOG
Trace records are written to different logs under CICS, IMS TM and MVS:
Under CICS, tracing functions use VSAM files as log files. The default file name is SYTDLOG1.
Under IMS TM, tracing functions use the IMS TM log.
Under MVS, the records are written to a sequential file. The DDNAME of this file is specified as a parameter in TDCUSTOM (MVSDDNAME).

**Table 1-1: Coding differences between CICS, IMS TM and MVS**
Function	Difference Between CICS, IMS TM and MVS
TDINFRPC TDSTATUS	The action taken when the communication state (COMM-STATE) is TDS-RESET can differ between CICS, MVS and the IMS TM implicit API: Under CICS, MVS, and the IMS TM explicit API, the transaction exits as soon as possible. Under the IMS TM implicit API, the transaction can call TDGETREQ to accept another client request or it can exit.
TDINIT	The first argument differs between CICS and IMS TM: Under CICS, the communications I/O block, passed as the first parameter in TDINIT, is the EIB (DFHEIBLK). Under IMS TM, the first TDINIT parameter is I/O PCB (IO-PCB). Under MVS, a null pointer should be used.
TDSETPT	Used with IMS TM only, to indicate the type of IMS TM transaction.
TDSNDDON	Value of CONN-OPTIONS in CICS, MVS, and the IMS TM explicit API can be set to TDS-ENDREPLY in long-running transactions. TDS-ENDREPLY cannot be used under the IMS TM implicit API. To learn how to simulate long-running transactions in the implicit API, see "Long-Running Transactions".
TDINFACT TDSETACT	Accounting records are written to different logs under CICS, IMS TM and MVS: Under CICS, accounting functions use VSAM files as log files. The default file name is SYTACCT1. Under IMS TM, accounting functions use the IMS TM log. Under MVS, the records are written to a sequential file. The DDNAME of this file is specified as a parameter in TDCUSTOM (MVSDDNAME).
TDINFLOG TDINFSPT TDLSTSPT TDSETLOG TDSETSPT TDWRTLOG	Trace records are written to different logs under CICS, IMS TM and MVS: Under CICS, tracing functions use VSAM files as log files. The default file name is SYTDLOG1. Under IMS TM, tracing functions use the IMS TM log. Under MVS, the records are written to a sequential file. The DDNAME of this file is specified as a parameter in TDCUSTOM (MVSDDNAME).

General Processing Procedures

Whether the incoming request is an RPC or a language, cursor, or dynamic request, the server application performs five general steps:

Prepares the environment
Accepts the request and retrieves the language, cursor, or dynamic request or RPC parameters
Performs the requested action
Returns results to the requesting client
Ends the conversation

This section shows how to perform four of these tasks using Gateway-Library functions. The remaining task (the requested action) is performed using familiar programming procedures. See Chapter 3, "Functions," for detailed information about each function.

Note: The tables in the following sections cover only the basic function sequences. Refer to the sample programs that come with Open ServerConnect and the examples to see how these functions are used in context.

Processing an RPC

When a client sends an RPC, a typical mainframe server application (short transaction) performs the tasks in the following table. The arrows in the table indicate code loops.

Table 1-2: Functions to process RPCs
Task
Function
1. Prepare for incoming requests.

Initialize the Gateway-Library environment.
Specify the type of IMS TM transaction (used with IMS TM transactions only).

TDINIT
TDSETPT
2. Accept the incoming request.

Accept the incoming request. �

TDACCEPT
3. Handle incoming parameters.

Determine how many parameters were sent.
Define variables for storing parameter information (datatype, length, data).
� Retrieve the parameter. (Loop until all parameters are retrieved.)

TDNUMPRM
TDINFPRM
TDRCVPRM
4. Process the request.

Perform the requested task(s).
5. Prepare to return results to the client.

� Set the length and address of each return parameter. (Loop until all parameters are described.)

� Describe each column in a row to be returned. (Loop until all columns are retrieved.)

TDSETPRM

TDESCRIB
6. Return data to the client.

� Send data to the client, one row at a time. (Loop until all rows are sent.)

Send the return parameters, tell the client when results are finished, and close the connection.

TDSNDROW

TDSNDDON
7. End the conversation.

Free the TDPROC structure.
Free the MVS storage (required with IMS TM; optional but recommended with CICS).

TDFREE
TDTERM

**Table 1-2: Functions to process RPCs**
Task	Function
1. Prepare for incoming requests. Initialize the Gateway-Library environment. Specify the type of IMS TM transaction (used with IMS TM transactions only).	TDINIT TDSETPT
2. Accept the incoming request. Accept the incoming request. �	TDACCEPT
3. Handle incoming parameters. Determine how many parameters were sent. Define variables for storing parameter information (datatype, length, data). � Retrieve the parameter. (Loop until all parameters are retrieved.)	TDNUMPRM TDINFPRM TDRCVPRM
4. Process the request. Perform the requested task(s).
5. Prepare to return results to the client. � Set the length and address of each return parameter. (Loop until all parameters are described.) � Describe each column in a row to be returned. (Loop until all columns are retrieved.)	TDSETPRM TDESCRIB
6. Return data to the client. � Send data to the client, one row at a time. (Loop until all rows are sent.) Send the return parameters, tell the client when results are finished, and close the connection.	TDSNDROW TDSNDDON
7. End the conversation. Free the TDPROC structure. Free the MVS storage (required with IMS TM; optional but recommended with CICS).	TDFREE TDTERM

Processing a SQL Language Request

When a client sends a SQL select language request, a typical mainframe server application (short transaction) performs the tasks in the following table. The arrows in the table indicate code loops.

Table 1-3: Functions to process language requests
Task
Function
1. Prepare for incoming requests.

Initialize the Gateway-Library environment.
Specify the type of IMS TM transaction (used with IMS TM transactions only).

TDINIT
TDSETPT
2. Accept the incoming request.

Accept the incoming request.

TDACCEPT
3. Handle incoming SQL statements.

Determine the length (in bytes) of the incoming SQL string.
� Retrieve the SQL string. (Loop until all parameters are retrieved.)

TDSQLLEN
TDRCVSQL
4. Process the request.

Retrieve the requested data from the database.
5. Prepare to return results to the client.

� Set the length and address of each return parameter. (Loop until all parameters are described.)

� Describe each column in a row to be returned. (Loop until all columns are retrieved.)

TDSETPRM

TDESCRIB
6. Return data to the client.

� Send data to the client, one row at a time. (Loop until all rows are sent.)

Send the return parameters, tell the client when results are finished, and close the connection.

TDSNDROW

TDSNDDON
7. End the conversation.

Free the TDPROC structure.
Free the MVS storage (required with IMS TM; optional but recommended with CICS).

TDFREE
TDTERM

**Table 1-3: Functions to process language requests**
Task	Function
1. Prepare for incoming requests. Initialize the Gateway-Library environment. Specify the type of IMS TM transaction (used with IMS TM transactions only).	TDINIT TDSETPT
2. Accept the incoming request. Accept the incoming request.	TDACCEPT
3. Handle incoming SQL statements. Determine the length (in bytes) of the incoming SQL string. � Retrieve the SQL string. (Loop until all parameters are retrieved.)	TDSQLLEN TDRCVSQL
4. Process the request. Retrieve the requested data from the database.
5. Prepare to return results to the client. � Set the length and address of each return parameter. (Loop until all parameters are described.) � Describe each column in a row to be returned. (Loop until all columns are retrieved.)	TDSETPRM TDESCRIB
6. Return data to the client. � Send data to the client, one row at a time. (Loop until all rows are sent.) Send the return parameters, tell the client when results are finished, and close the connection.	TDSNDROW TDSNDDON
7. End the conversation. Free the TDPROC structure. Free the MVS storage (required with IMS TM; optional but recommended with CICS).	TDFREE TDTERM

Processing a Cursor Request

When a client sends a cursor request, a typical mainframe server application performs the tasks in the following table.

Table 1-4: Functions to process cursor requests
Task
Function
1. Prepare for incoming requests.

Initialize the Gateway-Library environment.
Specify the type of IMS TM transaction (used with IMS TM transactions only).

TDINIT
TDSETPT
2. Accept the incoming request.

Accept the incoming request.

TDACCEPT
3. Determine the type of request.

Determine the type of client request: RPC, language, dynamic, or cursor.

TDINFPGM
4. Determine the type of cursor request.

Retrieve CURSOR-COMMAND, CURSOR-ID, and COMMAND-OPTIONS.

TDCURPRO
5. Process the cursor request.

Get SQL statement, number of parameters, table name, and parameters format.

Either receive input parameters or update columns.

TDRCVSQL
TDNUMPRM
TDINFPRM
TDRCVPRM
6. Describe the rows.

Describe the rows.
Send rows.

TDESCRIB
TDSNDROW
7. Send return information.

Send acknowledgment, CURSOR-STATUS, CURSOR-INFO.

TDCURPRO
8. Send DONE.

Send a DONE package.

TDSNDDON
9. Accept the next request.

Accept the incoming request.

TDGETREQ
10. End the conversation.

Send final DONE package.
Free the TDPROC structure.
Free the MVS storage.

TDSNDDON
TDFREE
TDTERM

**Table 1-4: Functions to process cursor requests**
Task	Function
1. Prepare for incoming requests. Initialize the Gateway-Library environment. Specify the type of IMS TM transaction (used with IMS TM transactions only).	TDINIT TDSETPT
2. Accept the incoming request. Accept the incoming request.	TDACCEPT
3. Determine the type of request. Determine the type of client request: RPC, language, dynamic, or cursor.	TDINFPGM
4. Determine the type of cursor request. Retrieve CURSOR-COMMAND, CURSOR-ID, and COMMAND-OPTIONS.	TDCURPRO
5. Process the cursor request. Get SQL statement, number of parameters, table name, and parameters format. Either receive input parameters or update columns.	TDRCVSQL TDNUMPRM TDINFPRM TDRCVPRM
6. Describe the rows. Describe the rows. Send rows.	TDESCRIB TDSNDROW
7. Send return information. Send acknowledgment, CURSOR-STATUS, CURSOR-INFO.	TDCURPRO
8. Send DONE. Send a DONE package.	TDSNDDON
9. Accept the next request. Accept the incoming request.	TDGETREQ
10. End the conversation. Send final DONE package. Free the TDPROC structure. Free the MVS storage.	TDSNDDON TDFREE TDTERM

Processing a Dynamic SQL Request

When a client sends a dynamic request, a typical mainframe server application performs the tasks in the following table.

Table 1-5: Functions to process dynamic requests
Task
Function
1. Prepare for incoming requests.

Initialize the Gateway-Library environment.
Specify the type of IMS TM transaction (used with IMS TM transactions only).

TDINIT
TDSETPT
2. Accept the incoming request.

Accept the incoming request.

TDACCEPT
3. Determine the event type.

Determine the type of client request: RPC, language, dynamic, or cursor.

TDINFRPC
4. Determine the type of dynamic operation.

This can be a dynamic prepare request, dynamic execute request, dynamic execute immediate request, request for input or output parameter descriptions, or deallocate request.

TDYNAMIC
5. Process dynamic operation.

Get the statement (for prepare).
Get the statement ID (for all dynamic requests).

TDYNAMIC
6. Handle the incoming parameters.

Determine number of parameters (for execute).
Retrieve number of parameters (for execute).
Retrieve input parameters (for execute).

TDNUMPRM
TDINFPRM
TDRCVPRM
7. Describe the data.

Describe input/output parameters, or rows to be returned.

TDSNDROW
8. Return data to the client.

Send result rows for execute or execute immediate.
Send an acknowledge request.
Send a done package.

TDYNAMIC
TDSNDDON
9. Get the next request type.

Accept the incoming request.

TDGETREQ
10. End the conversation.

Send final DONE package.
Free the TDPROC structure.
Free the MVS storage.

TDSNDDON
TDFREE
TDTERM

**Table 1-5: Functions to process dynamic requests**
Task	Function
1. Prepare for incoming requests. Initialize the Gateway-Library environment. Specify the type of IMS TM transaction (used with IMS TM transactions only).	TDINIT TDSETPT
2. Accept the incoming request. Accept the incoming request.	TDACCEPT
3. Determine the event type. Determine the type of client request: RPC, language, dynamic, or cursor.	TDINFRPC
4. Determine the type of dynamic operation. This can be a dynamic prepare request, dynamic execute request, dynamic execute immediate request, request for input or output parameter descriptions, or deallocate request.	TDYNAMIC
5. Process dynamic operation. Get the statement (for prepare). Get the statement ID (for all dynamic requests).	TDYNAMIC
6. Handle the incoming parameters. Determine number of parameters (for execute). Retrieve number of parameters (for execute). Retrieve input parameters (for execute).	TDNUMPRM TDINFPRM TDRCVPRM
7. Describe the data. Describe input/output parameters, or rows to be returned.	TDSNDROW
8. Return data to the client. Send result rows for execute or execute immediate. Send an acknowledge request. Send a done package.	TDYNAMIC TDSNDDON
9. Get the next request type. Accept the incoming request.	TDGETREQ
10. End the conversation. Send final DONE package. Free the TDPROC structure. Free the MVS storage.	TDSNDDON TDFREE TDTERM

Processing a Long-Running Transaction

When a client sends a series of RPCs, a typical mainframe server application (long-running transaction) performs the tasks in the following table. The arrows in the table indicate code loops.

Table 1-6: Functions to process long-running transactions
Task
Function
1. Prepare for incoming requests.

Initialize the Gateway-Library environment.
Specify the type of IMS TM transaction (used with IMS TM transactions only).

TDINIT
TDSETPT
2. Accept the incoming request.

Accept the incoming request.

TDACCEPT
3. Handle incoming parameters.

Determine how many parameters were sent.
� Loop until all parameters are retrieved.

TDNUMPRM
TDINFPRM
TDRCVPRM
4. Process the request.

Perform the requested task(s).
5. Prepare to return results to the client.

� Loop to describe return parameters and columns in return rows.

TDSETPRM
TDESCRIB
6. Return data to the client

� Send rows and return parameters to the client. (For final TDSNDDON, you must set STATUS to TDS-DONE-FINAL and CONN-OPTIONS to TDS-ENDREPLY.)

TDSNDROW
TDSNDDON
7. Accept next request.

Accept the incoming request.

TDGETREQ
8. Repeat steps 3-6.

Repeat steps 3-6 for each successive request. (For final TDSNDDON, you must set STATUS to TDS-DONE-FINAL and CONN-OPTIONS to TDS-ENDRPC.)
9. End the conversation.

Free the TDPROC structure.
Free the MVS storage (required with IMS TM; optional but recommended with CICS).

TDFREE
TDTERM

**Table 1-6: Functions to process long-running transactions**
Task	Function
1. Prepare for incoming requests. Initialize the Gateway-Library environment. Specify the type of IMS TM transaction (used with IMS TM transactions only).	TDINIT TDSETPT
2. Accept the incoming request. Accept the incoming request.	TDACCEPT
3. Handle incoming parameters. Determine how many parameters were sent. � Loop until all parameters are retrieved.	TDNUMPRM TDINFPRM TDRCVPRM
4. Process the request. Perform the requested task(s).
5. Prepare to return results to the client. � Loop to describe return parameters and columns in return rows.	TDSETPRM TDESCRIB
6. Return data to the client � Send rows and return parameters to the client. (For final TDSNDDON, you must set STATUS to TDS-DONE-FINAL and CONN-OPTIONS to TDS-ENDREPLY.)	TDSNDROW TDSNDDON
7. Accept next request. Accept the incoming request.	TDGETREQ
8. Repeat steps 3-6. Repeat steps 3-6 for each successive request. (For final TDSNDDON, you must set STATUS to TDS-DONE-FINAL and CONN-OPTIONS to TDS-ENDRPC.)
9. End the conversation. Free the TDPROC structure. Free the MVS storage (required with IMS TM; optional but recommended with CICS).	TDFREE TDTERM

Additional Processing Options

The following table contains additional Gateway-Library functions for occasional use:

Table 1-7: Functions for process options
Task
Function
Locate the decimal point for each column.
TDSETBCD
Convert mainframe datatypes to those used by DB-Library programs.
TDCONVRT
Return information about the currently running transaction.
TDINFPGM
Return information about the current client request.
TDINFRPC
Return information about the user-defined datatype associated with a column.
TDINFUDT
Change data length of a column before sending the row.
TDSETLEN
Specify the Gateway-Library datatype for a column.
TDSETUDT
Send error or informational messages to the client.
TDSNDMSG
Retrieve status information about the connection.
TDSTATUS
Retrieve client login information.
TDGETUSR

**Table 1-7: Functions for process options**
Task	Function
Locate the decimal point for each column.	TDSETBCD
Convert mainframe datatypes to those used by DB-Library programs.	TDCONVRT
Return information about the currently running transaction.	TDINFPGM
Return information about the current client request.	TDINFRPC
Return information about the user-defined datatype associated with a column.	TDINFUDT
Change data length of a column before sending the row.	TDSETLEN
Specify the Gateway-Library datatype for a column.	TDSETUDT
Send error or informational messages to the client.	TDSNDMSG
Retrieve status information about the connection.	TDSTATUS
Retrieve client login information.	TDGETUSR

Tracing and Accounting Functions

The following table contains Gateway-Library functions that are available for tracing and accounting. These functions are used primarily by a system programmer.

Table 1-8: Functions for tracing and accounting
Task
Function
Turn mainframe-based tracing on or off.
TDSETLOG
Write a user-defined or system entry to the trace/error log.
TDWRTLOG
Return trace setting information.
TDINFLOG
Set tracing on or off for a specified transaction.
TDSETSPT
List all transactions for which specific tracing is enabled.
TDLSTSPT
Indicate whether tracing is on or off for a specified transaction.
TDINFSPT
Turn mainframe-based accounting on or off.
TDSETACT
Determine whether accounting is on and the name of the accounting log file.
TDINFACT

Task	Function
Turn mainframe-based tracing on or off.	TDSETLOG
Write a user-defined or system entry to the trace/error log.	TDWRTLOG
Return trace setting information.	TDINFLOG
Set tracing on or off for a specified transaction.	TDSETSPT
List all transactions for which specific tracing is enabled.	TDLSTSPT
Indicate whether tracing is on or off for a specified transaction.	TDINFSPT
Turn mainframe-based accounting on or off.	TDSETACT
Determine whether accounting is on and the name of the accounting log file.	TDINFACT


	Expand Search