Although CLI2MCI is the only annotated listing, the notes can also be used to review CLI2MPI, a direct PL/I counterpart of CLI2MCI.
| Note | Annotation |
|---|---|
| 1 | NUMLOG is a program constant which specifies the number of sessions to be connected. |
| 2 | MAXTRANS is a program constant that specifies the number of transactions to be initiated for each iteration of the conversation. |
| 3 | COBOL programs must specify Move Mode Fetch. The response buffer size must be specified when in move mode. Paragraph DBCAREA-SETUP indicates move mode by setting DBCAREA-LOC-MODE to N and DBCAREA-FET-I-MAX-DATA-LEN to the response buffer size. |
| 4 | The IMS SPA area is used to retain the logon string and data values across iterations of the conversation. The iteration count is also maintained in the SPA. |
| 5 | The Teradata SQL request in this example consists of multiple statements per request. Thus, each transaction consists of five insert and five update statements which must complete as a group (that is, all or none). MAXTRANS such transactions are initiated for each iteration of the program. |
| 6 | Since a USING modifier precedes the request, data must by supplied by the program. In this case the data is described as five integer values which are initially set to 1,2,3,4,5. |
| 7 | Use the standard DBCAREA COPY member DBCAREAC in COBOL application programs, and the standard COBOL COPY member CLIPARMC in COBOL programs to define various CLI and parcel constants. |
| 8 | A variable length data item VARMSG is used to handle the variable length messages returned by failure and error parcels. |
| 9 | TOKEN-ARRAY is the structure used to hold values related to each session. This program is designed to use only one copy of a DBCAREA. Values related to a particular session are indexed by a TOKEN which is specified by the program when a session is connected. This TOKEN is retained by CLI2 at CONNECT time and returned to the program after a call to DBCHWAT. The program can then use the returned TOKEN as an index to obtain values from the TOKEN-ARRAY and store into the DBCAREA, or to obtain values from the DBCAREA and store into the TOKEN-ARRAY. |
| 10 | The IMS sample programs reference only the IO/PCB. Your application program can define any number of PCBs. |
| 11 | This conversational program is designed to process messages until the PROCLIM value is exceeded or until no message is available (that is, status = QC). The transaction can be scheduled to execute in any number of MPP regions with SCHDTYP=PARALLEL or SERIAL. |
| 12 | The CLI2 related functions are performed in the paragraphs (procedure for PL/I programs) starting with INSERT-ROWS. The remaining paragraphs handle the IMS related functions which deal with ISRTing the response message, ISRTing the SPA, and then asking for more work (messages). |
| 13 | ISRT “Transaction Completed” message. |
| 14 | ISRT “Enter YES or NO” message. If YES is entered, the program retrieves the data values of the previous iteration from the SPA and continues to generate (insert/update) more rows into the table. If NO is entered, the program terminates the conversation by storing blanks in the TRANCODE field of the SPA, ISRTing the message and ISRTing the SPA. |
| 15 | Whenever the application program is entered, it must perform the initialization function (that is, call DBCHINI). This is true for programs designed to process either non-conversational or conversational transactions. DBCHINI must be called on every iteration of a conversation. Use session pooling (see Teradata Director Program Reference [B035-2416] for more information) to avoid actual Teradata DBS logons for each transaction. Note that DBCHINI will verify the length value stored in DBCAREA and then CLEAR the DBCAREA to binary zeros. The EYE-CATCHER field will then be set by DBCHINI. Thus, the VALUE (COBOL) and INIT (PL/I) clauses which are specified in the program (or in the COPY/INCLUDE members) have no significance. |
| 16 | Set the address of the LOGON string into the DBCAREA field DBCAREA-LOGON-PTR. Note that this program identifies DBCAREA fields with the prefix DBC. The recommended method is to use the standard DBCAREA definitions (that is, COPY DBCAREAC for COBOL programs or %INCLUDE DBCAREAP for PL/I programs). DBCAREAC identifies DBCAREA fields with names that begin with “DBCAREA-”. DBCAREAP declares PL/I variables without using “DBCAREA” as part of the name. The qualifier “DBCAREA.” can be used to identify DBCAREA variables in a PL/I program. Note that DBCHSAD is called by COBOL programs to store address type values in DBCAREA. PL/I uses the ADDR function to store addresses. |
| 17 | On the first entry of the conversation, this particular program calls an external subroutine (CLI2CTB) to DROP and then CREATE a table (MYTABLE2). Note that the logon string is stored in the DBCAREA prior to the call. The subroutine is passed the address of the DBCAREA (contained in the calling program’s storage area), and the address of another area, MSG-INFO, used to pass error/failure indicators and messages between the programs. The calling program performs all IMS message handling. The called program CLI2CTB is a COBOL program which is called by the COBOL sample programs (CLI2MCB and CLI2MCI) and the PL/I sample programs (CLI2MPB and CLI2MPI). |
| 18 | On return from the sub program, the MSG-INFO area is checked for indications of error/failure during the CREATE TABLE process. |
| 19 | Also, only on first entry, the generated data values are initialized. An application program would, for example, position to the database segment containing the first segment to be processed. |
| 20 | Connect the number of concurrent sessions required by the program. This program connects ALL of the sessions (call DBCHCL after setting the CONNECT-FUNC function code in the DBCAREA) prior to executing a call to DBCHCL to FETCH the response parcels (a successful CONNECT results in no parcels being returned); a CLI EOF code will be returned for the FETCH call. |
| 21 | The WAIT-FETCH-IRQ paragraph/procedure is performed/called to perform the following sequence. WAIT for a request to complete. FETCH and process each response parcel. If FETCH-EOF, then end (close) the request and initiate a new request. If BUSY, go back to WAIT. Note that the first attempt to fetch a response after CONNECT will always produce a BUSY CLI code (or failure), even after waiting (call to DBCHWAT). This is explained as follows: The CONNECT process is a two-step process, LOGON and RUN. The first return from wait indicates that the logon has completed. The attempt to fetch, however, will return an indication that the session is busy (processing the RUN request). This sequence may change in a future release. An application program which is written to return to WAIT after a BUSY return code should be compatible with a future change which combines the LOGON/RUN into a single request. When there is no more work (rows to be inserted in this example), the session whose TOKEN was returned by DBCHWAT will be disconnected by the application program. The program will then WAIT again for the next available session (which will also be disconnected because of lack of work). When all sessions have been disconnected, the processing is terminated. |
| 22 | Wait for session not pending. |
| 23 | Use TOKEN returned by DBCHWAT as an index into TOKEN-ARRAY. |
| 24 | Move the related logical session id and request id to the DBCAREA in preparation for FETCH calls. |
| 25 | FETCH and process parcels until EOF or BUSY or CRASH codes. |
| 26 | If EOF and last function was LOGON (really CONNECT), then save the actual (not logical) TDP session id (TDPSESS) in the related element of TOKEN-ARRAY. Note that the only time that a valid TDPSESS value will be available is after the FETCH-EOF which occurs after the CONNECT function. |
| 27 | End the request (call DBCHCL with END-REQUEST-FUNC) after FETCH-EOF. If the end request call is not made after FETCH-EOF. The control blocks maintained by CLI2 will accumulate and unnecessarily consume storage. A large number of unended requests may result in the abnormal termination of the program. |
| 28 | If more transactions need to be processed, perform the INITIATE-REQ-FUNC function. |
| 29 | ELSE disconnect the session and reduce the session counter. |
| 30 | The following values are initialized in the DBCAREA:
|
| 31 | The size of the parcel area is also required to be set by COBOL program. |
| 32 | Setting the “maximum number of sessions” is not mandatory but will assist CLI2 in its space management functions. |
| 33 | Setting Locate Mode to N (NO) is required for COBOL program. |
| 34 | Set N value for Wait For Response if your program is designed to manage multiple sessions with overlap of DBC and host processing. Programs which do not call DBCHWAT should use the default value Y (yes, wait for response). |
| 35 | This program set N for crash-wait. CLI2 will not wait for completion of the DBC crash recovery process and the DBC session will terminate. |
| 36 | This program set Y for crash-tell. CLI2 will indicate that a crash has occurred. However, since the Crash Wait option was set to N the program cannot prompt the user to determine if he/she wants to wait on Teradata DBS recovery. A better combination for an interactive program is the default set of Y Y. If the user does not wish to wait, then the session can be aborted by the program. |
| 37 | The Change option must be set to Y to trigger the changing of the options. |