In this section: |
This topic contains overview, configuration, and installation information (as applicable) for the following IMS/TM procedures:
The CALLIMS and CALLITOC procedures for IMS/TM hide the complexity of accessing IMS/TM transactions from the client application. The client application uses any major standard access protocol to connect to a server and invoke the adapter to access the IMS/TM transaction. The standard protocols include ODBC, JDBC, OLE DB, or any enabled client or connector.
The Adapter for IMS Transactions allows any client or connector to invoke a transaction running under the control of an IMS/TM transaction-processing monitor. It provides a means of building on existing applications that perform transaction processing against IMS/TM, to create new Web or client/server applications while reusing existing IMS transactions and program logic.
For related information, refer to the API Reference manual for API method calls and the Stored Procedure Reference manual for details about writing Dialogue Manager procedures.
The CALLIMS procedure is part of the server for z/OS. It is attached to and extended from any compatible API environment, including client applications and Hub Servers.
The CALLIMS procedure uses LU6 communications from a server for z/OS to execute IMS/TM transactions, and passes the output to any client that connects to that server.
The OTMA procedure fully utilizes the IMS TOC functionality. The IMS TCP/IP Connector (ITOC) and its equivalent product, IMS Connect, is available with IMS Version 7.1 and higher, and allows client TCP/IP communications to and from one or more IMS/TM regions. TOC and IMS Connect are IBM's implementation for allowing the execution of IMS/TM transactions from TCP/IP clients.
The following steps are performed when a client application calls an IMS/TM transaction using either the CALLIMS or CALLITOC procedure. The difference between the CALLIMS and the CALLITOC procedures is the communications method used to connect to the IMS/TM region from the client application. Also, CALLIMS requires a server for z/OS to initiate the IMS/TM request. Any client on any platform can connect to the server for z/OS.
Parameters are sent as part of the calling sequence for use by the procedure.
For details on the syntax and use of API method calls, see the API Reference manual.
The following figure illustrates transaction processing as initiated by the client application running a CALLIMS request.
The following figure illustrates transaction processing as initiated by the client application running a CALLITOC OTMA request.
Reference: |
To call an IMS/TM transaction, execute either CALLIMS or CALLITOC from a Dialogue Manager procedure:
A sample RPC called CALLIMSC is supplied with the Server. It executes the IMS/TM PART transaction for verification and installation purposes.
There are several differences between the CALLIMS and the CALLITOC procedures:
CALLIMS and CALLITOC return codes and data to the client application in a series of 72-byte messages. To retrieve the messages, the client application issues the method call EDAACCEPT.
Repeated calls to EDAACCEPT retrieve all messages from CALLIMS and CALLITOC.
The client application must check the message code in the field scb.msg_code. (The session control block contains several fields pertaining to message processing. For example, scb.msg_code contains a message code and scb.msg_text contains the message text.)
A code of 4245 indicates that the message is coming from CALLIMS or CALLITOC.
For the client application to detect multiple output segments, the Adapter for IMS Transactions returns a message code of 4246 following the 4245, until the end of the segment. At that time, the message code is again 4245, indicating the beginning of a new segment.
The following figure illustrates the message codes from CALLIMS or CALLITOC when there are multiple output segments. The client application normally changes the received format to a format acceptable to the end user.
In this section: |
Complete the following installation steps:
CALLIMS requires the following hardware and software:
CALLIMS communicates with APPC to execute IMS/TM transactions. APPC includes an interface to IMS called APPC/IMS. The APPC/IMS interface must be correctly configured to support IMS/TM transactions.
APPC components that may be used by CALLIMS include:
Note: The APPC Transaction Scheduler (ASCH) must be fully configured and running in order for CALLIMS to communicate successfully with APPC/IMS. See the appropriate IBM APPC documentation for configuration instructions.
To establish conversation security with APPC/IMS, define the environment under which the partner (the other end of the conversation with IMS/TM) will run.
The two possible security levels are:
This security level is the default if no security information is explicitly provided in the CALLIMS function.
The CALLIMS subroutine communicates with APPC using the APPC API. To establish communication between CALLIMS and APPC, you must link-edit the API.
To link-edit the API, submit the following job
qualif.HOME.DATA(GENEAPPC)
where:
Is the high-level qualifier for the data sets.
The following JCL is located in member GENEAPPC in the library qualif.HOME.DATA. It must be modified and run.
//******************************************************************** //* NAME: GENEAPPC JCL //* //* FUNCTION: LINKEDIT APPC STUBS INTO CALLIMS //* //* PROC SYMBOLIC PARAMETERS: //* 1. qualif MUST BE CHANGED TO THE HIGH LEVEL QUALIFIER //* USED FOR THE PROGRAM DATASETS UNLOAD FROM THE MEDIA //* //********************************************************************
//APPROC PROC PREFIX='qualif' //* //LKED EXEC PGM=IEWL,PARM='RENT,LIST,NOXREF,LET' //SYSLIB DD DISP=SHR,DSN=SYS1.CSSLIB //SYSIN DD DISP=SHR,DSN=&PREFIX..HOME.LOAD //SYSLMOD DD DISP=SHR,DSN=&PREFIX..HOME.LOAD //* Switch the above two lines with the following for PDS deployment //*SYSIN DD DISP=SHR,DSN=&PREFIX..P.HOME.LOAD //*SYSLMOD DD DISP=SHR,DSN=&PREFIX..P.HOME.LOAD //SYSUT1 DD UNIT=SYSDA,SPACE=(100,(50,50)) //SYSPRINT DD SYSOUT=A //* //APPROC PEND //GENFAPPC EXEC APPROC //LKED.SYSLIN DD * INCLUDE SYSIN(CALLIMS) INCLUDE SYSLIB(ATBPBI) MODE AMODE(31),RMODE(ANY) ENTRY CALLIMS NAME CALLIMS(R) /*
The Transaction Server for IMS provides a sample REXX EXEC that helps confirm the successful installation of APPC and APPC/IMS. The EXEC will invoke an existing MPP.
To use the sample EXEC, which is located in qualif.HOME.DATA(APPCIVP):
The following table lists and describes the default values:
Values |
Description |
---|---|
TP_name = 'PART' |
The name of the transaction to invoke. |
Sym_dest_name = 'IMSDEST' |
The symbolic destination name found in the side information data set. |
Mode_name = 'LU62APPC' |
The log mode table entry name used by the LU6.2 APPLID supplied on the next keyword. |
Partner_LU_Name = 'SCMI41AX' |
The LU6.2 APPLID defined for use by APPC/IMS. |
Partnumber = 'AN960C10' |
The input data for the transaction. |
EX 'qualif.HOME.DATA(APPCIVP)' EXEC
This routine confirms that APPC/IMS is correctly configured to operate in a client/server environment. The next step enables the server to initiate an IMS connection.
How to: |
CALLIMS or CALLITOC is executed from a Dialogue Manager procedure with the command -SET.
Any of the variables described in the syntax that follows may be implicitly set in the Dialogue Manager procedure using the command -DEFAULTS, or explicitly set on the CALLIMS or CALLITOC call. The variables work the same way, whether set implicitly or explicitly. If both ways are used, the explicit setting takes precedence over the implicit setting. For examples of implicit settings, see Using -SET to Execute CALLITOC and Using -SET to Execute CALLIMS.
The dash (-) in the syntax below is used to allow multiple lines for a parameter list in a Dialogue Manager command, as in -SET
-SET &REPLY = CALLIMS(&SYM,&TP,&MLEN,&MSG,&DELIM,&OPT,&UID, - &PW,&SG,&PLU,&LMODE,&HEXCONV,'A1') ;
where:
Is the symbolic destination name. This is a key value for the side information data set configuration file defined to APPC. APPC supports a symbolic destination name for determining the default APPLID for the IMS/TM region, with a log mode and transaction name. If a value is supplied for &SYM, either implicitly or explicitly, then &TP, &PLU, and &LMODE may be left blank. This field must be 8 characters in length.
Is the name of the IMS MPP transaction. This field must be 8 characters in length. Set &TP to blanks if you supply a value for &SYM.
Is the length of the IMS MPP message for the transaction. This is set with the Dialogue Manager LENGTH function in a -SET command.
Is the input message for the IMS transaction. This message must exactly match the layout expected by the transaction.
Is a non-blank character string used to delimit individual segments in this IMS message. Each delimited segment has its own SEND. This variable is designed for MPP transactions that expect to retrieve multiple segments from the message queue. The length of &DELIM must be 4 characters.
Specifies whether CALLIMS waits for a response. Possible values are:
REPL assumes synchronous operation. CALLIMS waits for a return code or other response from IMS/TM.
NORP sends the message, then immediately returns control to the server. CALLIMS does not wait for a response.
The length of &OPT must be 4 characters.
The following parameters are optional. If not used, the parameters must be padded with blanks.
Is the user ID that invokes the IMS MPP transaction. The length of &UID must be 8 characters.
Is the password used to invoke the IMS MPP transaction. The length of &PW must be 8 characters.
Is the security group that the user ID belongs to or is part of. The length of &SG must be 8 characters.
Is the LU6.2 APPLID for the IMS/TM region. The length of &PLU must be 8 characters. Set &PLU to blanks if you supply a value for &SYM.
Is the log mode table entry name. The length of &LMODE must be 8 characters. Set &LMODE to blanks if you supply a value for &SYM.
A value of ON will truncate the message returned after any hex character data. OFF is the default.
Sets the format of the response to alphanumeric. It is required by -SET.
The dash (-) in the syntax below is used to allow multiple lines for a parameter list in a Dialogue Manager command, as in -SET
-?SET &REPLY = CALLITOC(&HOST, &PORT, &DSID, &TPNAME, &MLEN, &MESSAGE, -? &USERID, &RUSERID, &RGROUP, &PASSWD, &DELIM, &HEXCONV, &OPTION, &OTMAEX 'A1');
where:
Is the symbolic destination name. TCP/IP is the host address where IMS Connect or ITOC is running. &host is the value in the HOSTNAME=host in the HWS configuration file.
Is the port number that IMS Connect or ITOC is listening on. &port is the value in the PORTID=port in the HWS configuration file.
Is the value in the DATASTORE ID=dsid in the HWS configuration file.
Is the name of the IMS MPP transaction. This field must be 8 characters in length.
Is the length of the IMS MPP message for the transaction. This is set with the Dialogue Manager LENGTH function in a -SET command.
Is the input message for the IMS transaction. This message must exactly match the layout expected by the transaction.
Is the ITOC user ID. This user ID is reserved for future use.
Is the user ID that is validated by RACF based on the RGROUP value.
Is the XCF group validated by RACF. &rgroup is the value in the GROUP=rgroup in the HWS configuration file.
Is the RACF password based on the RUSERID value.
Is a non-blank character string used to delimit individual segments in this IMS message. Each delimited segment has its own SEND. This variable is designed for MPP transactions that expect to retrieve multiple segments from the message queue. The length of &DELIM must be 4 characters.
A value of ON will truncate the message returned after any hex character data. OFF is the default.
Specifies whether CALLITOC waits for a response. Possible values are:
REPL assumes synchronous operation. CALLITOC waits for a return code or other response from IMS/TM.
NORP sends the message, then immediately returns control to the server. CALLITOC does not wait for a response.
The length of &OPT must be 4 characters.
Specifies which user message exit to use:
The sample user exits enable users to assign their own message formats to fit their business needs. See the IBM documentation for further information about sample user exits.
Sets the format of the response to alphanumeric. It is required by -SET.
The following is a sample Dialogue Manager procedure that uses the command -SET to execute CALLIMS. It is member CALLIMS of the data set.
In this example, values for variables are padded with blanks as required. The command -DEFAULTS enables you to specify default values in the Dialogue Manager procedure, but may be overridden by a client application:
-DEFAULTS &SYM = ' ' -DEFAULTS &TP = 'PART ' -DEFAULTS &MSG = 'AN960C10' -DEFAULTS &DELIM = ' ' -DEFAULTS &OPT = 'REPL' -DEFAULTS &UID = ' ' -DEFAULTS &PW = ' ' -DEFAULTS &SG = ' ' -DEFAULTS &PLU = 'SCMI41AX' -DEFAULTS &LMODE = 'LU62APPC' -SET &MLEN = &MSG.LENGTH; -SET &REPLY = CALLIMS(&SYM,&TP,&MLEN,&MSG,&DELIM,&OPT,&UID,&PW,&SG,&PLU,&LMODE,'A1');
The following is a sample Dialogue Manager procedure that uses the command -SET to execute CALLITOC. For a server for MVS, it is member CALLIMS of the data set.
In this example, values for variables are padded with blanks as required.
-DEFAULT &HOST= 'IBIMVS.IBI.COM '; -DEFAULT &PORT= 6683; -DEFAULT &DSID= 'IMS61 '; -DEFAULT &TPNAME= 'PART '; -DEFAULT &OPTION= 'REPL '; -DEFAULT &MESSAGE= 'AN960C10 '; -DEFAULT &USERID= ' '; -DEFAULT &RUSERID= ' '; -DEFAULT &RGROUP= 'IMSGRP61 '; -DEFAULT &PASSWD= ' '; -DEFAULT &DELIM= ' '; -DEFAULT &HEXCONV= ' '; -DEFAULTS &OTMAEX = '*SAMPLE*'
-SET &MLEN = &MESSAGE.LENGTH;
-SET &REPLY = CALLITOC(&HOST, - &PORT, - &DSID, - &TPNAME, - &MLEN, - &MESSAGE, - &USERID, - &RUSERID, - &RGROUP, - &PASSWD, - &DELIM, - &HEXCONV, - &OPTION, - &OTMAEX, - 'A1') ;
If you are using a front-end application, such as PowerBuilder, which cannot handle multiple messages, a method is needed to convert the messages into an answer set. This is especially important when using CALLIMS or CALLITOC, which only return messages.
The following stored procedure executes a CALLIMS procedure that returns 5 messages. Instead of sending the messages directly to the client, the stored procedure stores the messages in a file. A subsequent SELECT is performed to extract data, as an answer set, from the file. The stored procedure statements required for saving messages in the file are highlighted.
-SET &EMGSRV = 'FILE';
DYNAM ALLOC FILE EMGFILE DA qualif.EMGFIL SPACE 2,2 TRACKS UNIT SYSDA -
RECFM FB LRECL 80 BLKSIZE 1600
SET EMGSRV=&EMGSRV
SET PAUSE=OFF
-RUN
-DEFAULT &SYM = ' '
-DEFAULT &TP = 'PART '
-DEFAULT &MSG = 'AN960C10'
-DEFAULT &DELIM= ' '
-DEFAULT &OPT = 'REPL '
-DEFAULT &UID = ' '
-DEFAULT &PW = ' '
-DEFAULT &SG = ' '
-DEFAULT &PLU = 'SCMI41AX'
-DEFAULT &LMODE= 'LU62APPC'
-SET &MLEN = &MSG.LENGTH ; -SET &REPLY = CALLIMS(&SYM,&TP,&MLEN,&MSG,&DELIM,&OPT,&UID, - &PW,&SG,&PLU,&LMODE,'A1') ;
DYNAM FREE DDN EMGFILE
-RUN
DYNAM ALLOC FILE EMGSRV1 DA qualif.EMGFIL SHR REU
-RUN
SQL
SELECT COL1 FROM EMGSRV1;
TABLE
ON TABLE PCHOLD FORMAT ALPHA
END
DYNAM FREE DDN EMGSRV1
-RUN
For the SELECT COL1 FROM EMGSRV1 statement to work, a Master File has to be predefined for the file. The following is the Master File, EMGSRV1, used for this example:
FILENAME=EMGSRV1,SUFFIX=FIX SEGNAME=ORIGIN,SEGTYPE=S1 FIELDNAME=COL1,FIRST40,A40,$ FIELDNAME=COL2,LAST40,A40,$
The following is the output, from CALLIMS, which is placed into the file:
(FOC4245) : Part........... AN960C10; Desc........... WASHER (FOC4246) : (FOC4245) : Proc Code...... 74; Inv Code....... 2 (FOC4245) : Make Dept...... 12-00; Plan Rev Num... (FOC4245) : Make Time...... 63; Comm Code...... 14
Note: The second line is a FOC4246 message line, which indicates a continuation of the previous line. The sample stored procedure returns the first 40 bytes of all 5 records to the client. The stored procedure can be set to return the entire message.
iWay Software |