Invoking an IMS Stored Procedure

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.


Top of page

x
CALLIMS Procedure for IMS/TM

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.


Top of page

x
CALLITOC OTMA Procedure for IMS/TM

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.


Top of page

x
Transaction Processing With CALLIMS or CALLITOC

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.

  1. The client application issues the API method call, EDARPC, to run a Dialogue Manager procedure residing on a server (either a Hub Server or a Full-Function Server).

    Parameters are sent as part of the calling sequence for use by the procedure.

  2. The Dialogue Manager procedure contains the command -SET, which executes CALLIMS or CALLITOC.
  3. CALLIMS or CALLITOC establishes a connection to the IMS/TM environment and invokes the transaction, passing an IMS message as a parameter.
  4. The IMS transaction receives and then processes the input message. It then passes one IMS message back to the server. The CALLIMS or CALLITOC procedure returns the message to the client application.
  5. The client application issues the method call, EDAACCEPT, to accept the message.

For details on the syntax and use of API method calls, see the API Reference manual.



Example: Processing a Transaction With CALLIMS

The following figure illustrates transaction processing as initiated by the client application running a CALLIMS request.



Example: Processing a Transaction With CALLITOC OTMA

The following figure illustrates transaction processing as initiated by the client application running a CALLITOC OTMA request.


Top of page

x
Using CALLIMS and CALLITOC

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.



x
Reference: Differences Between CALLIMS and CALLITOC

There are several differences between the CALLIMS and the CALLITOC procedures:


Top of page

x
How Data Is Returned With CALLIMS and CALLITOC

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.



Example: Viewing Message Codes From CALLIMS or CALLITOC

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.


Top of page

x
Installing CALLIMS

In this section:

Complete the following installation steps:

  1. Step 1: Ensure That You Have the Required Hardware and Software
  2. Step 2: Determine the APPC Setup
  3. Step 3: Set the Security Level
  4. Step 4: Link-edit the API
  5. Step 5: Confirm Interaction With IMS/TM


x
Step 1: Ensure That You Have the Required Hardware and Software

CALLIMS requires the following hardware and software:



x
Step 2: Determine the APPC Setup

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.



x
Step 3: Set the Security Level

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:



x
Step 4: Link-edit the API

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:

qualif

Is the high-level qualifier for the data sets.



Example: Installing CALLIMS

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)                                                    
/*


x
Step 5: Confirm Interaction With IMS/TM

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):

  1. You may need to change the default EXEC values to execute the IMS IVP PART transaction.

    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.

  2. In case of errors, APPCIVP calls a standard REXX EXEC named IRXCKRC, so you must copy the EXEC from SYS1.SAMPLIB to qualif.HOME.DATA.
  3. After you make the necessary changes to APPCIVP and copy IRXCKRC, run the EXEC from TSO:
    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.



x
Executing CALLIMS and CALLITOC

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.



x
Syntax: How 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:

&SYM

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.

&TP

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.

&MLEN

Is the length of the IMS MPP message for the transaction. This is set with the Dialogue Manager LENGTH function in a -SET command.

&MSG

Is the input message for the IMS transaction. This message must exactly match the layout expected by the transaction.

&DELIM

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.

&OPT

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.

&UID

Is the user ID that invokes the IMS MPP transaction. The length of &UID must be 8 characters.

&PW

Is the password used to invoke the IMS MPP transaction. The length of &PW must be 8 characters.

&SG

Is the security group that the user ID belongs to or is part of. The length of &SG must be 8 characters.

&PLU

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.

&LMODE

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.

HEXCONV

A value of ON will truncate the message returned after any hex character data. OFF is the default.

'A1'

Sets the format of the response to alphanumeric. It is required by -SET.



x
Syntax: How to Execute CALLITOC OTMA

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:

&HOST

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.

&PORT

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.

&DSID

Is the value in the DATASTORE ID=dsid in the HWS configuration file.

&TPNAME

Is the name of the IMS MPP transaction. This field must be 8 characters in length.

&MLEN

Is the length of the IMS MPP message for the transaction. This is set with the Dialogue Manager LENGTH function in a -SET command.

&MESSAGE

Is the input message for the IMS transaction. This message must exactly match the layout expected by the transaction.

&USERID

Is the ITOC user ID. This user ID is reserved for future use.

&RUSERID

Is the user ID that is validated by RACF based on the RGROUP value.

&RGROUP

Is the XCF group validated by RACF. &rgroup is the value in the GROUP=rgroup in the HWS configuration file.

&PASSWD

Is the RACF password based on the RUSERID value.

&DELIM

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.

&HEXCONV

A value of ON will truncate the message returned after any hex character data. OFF is the default.

&OPTION

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.

&OTMAEX

Specifies which user message exit to use:

  • *SAMPLE* indicates HWSSMPL0
  • *SAMPL1* indicates HWSSMPL1

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.

'A1'

Sets the format of the response to alphanumeric. It is required by -SET.



Example: Using -SET to Execute CALLIMS

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');


Example: Using -SET to Execute CALLITOC

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') ;

Top of page

x
Storing Multiple Messages In a Server File for Later Queries

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.



Example: Storing Multiple Messages for Later Execution

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