Remote Stored Procedures

Remote Stored Procedures

Customer-written CICS application programs Provides LAN applications with access to CICS resources Invoked by LAN-based client or web application Invoked with USE or EXECUTE statement

From the Application Perspective . . .

Data returned from an RSP is no different than Data returned from an RSP is no different than data returned from a relational DBMS!data returned from a relational DBMS!

Stored Procedure Processing

Access Server

CICS

USE PROCEDURE PAYHISTUSE PROCEDURE PAYHISToror

EXECUTE PAYHISTEXECUTE PAYHIST

RSP

Why Use Remote Stored Procedures? Programmatic access to S/390 data and resources Access unusual data sources or difficult data structures Perform complex processing Execute existing business logic

Typical Uses for RSPs

Desktop and web access to non-relational data– VSAM– IMS and DL/I– Datacom, Adabas, IDMS– Others

Static access to DB2 Invocation of other CICS programs Access to other CICS resources ViaSQL TRANSFER operations

Modernize Existing CICS Applications Preserve investment in existing business logic and applications Just strip out the 3270 screen interactions Add the appropriate RSP commands Execute from desktop or web applications

Integrate 4GL Applications

Desktop and web access to S/390-based 4GL applications Ideal for access to Datacom/DB Natural for access to Adabas

Stored Procedure Programs

Customer written Standard CICS application program Supported languages

– COBOL II– Assembler– PL/I– C

Stored Procedure API

Easy to use CICS application issues Stored Procedure commands Issued via standard system CALL Stored Procedure Communication Area Stub routines

Stored Procedure Commands

STATUS indicate outcome of processing MESSAGE send a message to the workstation DESCRIBE obtain column information about a table COMMIT commit work ROLLBACK rollback work OPENPIPE open a data pipe GETPIPE read a record from the data pipe PUTPIPE write a record to the data pipe CLOSPIPE close the data pipe

Sample Stored ProcedureENVIRONMENT DIVISION.PROGRAM ID. PROGRAM3.*********************************************************************** INSERT A ROW INTO THE DB2 EMPLOYEE MASTER TABLE ***********************************************************************..

DATA DIVISION.01 EMPLOYEE-RECORD.

03 SSNO PIC X(11).03 NAME.

05 NAME-LEN PIC S9(4) COMP.05 NAME-TEXT PIC X(30).

03 HIREDATE PIC X(10).03 EXEMPTS PIC S9(4) COMP.03 WAGE PIC S999V99 COMP-3.

LINKAGE SECTION.01 DFHCOMMAREA.

COPY SPAREAC.

Sample Stored Procedure - continued

PROCEDURE-DIVISION.MOVE '522-80-3109' TO SSNO.MOVE 30 TO NAME-LEN.MOVE 'GROUCHO MARX' TO NAME-TEXT.MOVE '1988-03-27' TO HIREDATEMOVE 3 TO EXEMPTS.MOVE 12.25 TO WAGE.PERFORM -INSERT-EMPLOYEE.IF SQLCODE = 0 THEN PERFORM ISSUE-OK ELSE PERFORM ISSUE-ERROR.EXEC CICS RETURN.

INSERT-EMPLOYEE.EXEC SQL INSERT INTO Z271.SAMPLE_EMPLOYEE

(SSNO, NAME, HIRE_DATE, EXEMPTIONS, HOURLY_WAGE) VALUES(:SSNO, :NAME, :HIREDATE, :EXEMPTS, :WAGE)

ISSUE-OK.MOVE 'OK' TO SPSTATUS.CALL 'STATUS' USING SPAREA.

ISSUE-ERROR. MOVE 'E ' TO SPSTATUS. CALL 'STATUS' USING SPAREA.

Output Pipes

Used to return multiple rows of data Pipe must be open before use Pipe must be closed after use The PUTPIPE command is used to write data STD and DB2 format output pipes Access Server returns records in IXF format

STD Format Output Pipe

Stored procedure need not describe the data Stored procedure supplies data in free-form No data structure in IXF file

DB2 Format Output Pipe

Stored procedure describes data with SQLDA Stored procedure supplies data in DB2 format Data structure in captured in IXF file

Input Pipes

Used to read multiple rows of data Pipe must be opened before use Pipe must be closed after use GETPIPE command used to read records STD and DB2 format input pipes Server expects records in IXF format

The DB2 SQLDA Structure

Used with dynamic SQL SELECT statements Partially filled in when DESCRIBE is executed Describes the columns to be returned by a SELECT statement User must supply pointers to data and null indicators

SQLDA Structure

SQLTYPESQLTYPE SQLLENSQLLEN SQLDATASQLDATA SQLINDSQLIND SQLNAMESQLNAME

SQLDAIDSQLDAID

SQLDABCSQLDABC SQLNSQLN SQLDSQLD

Column 1 informationColumn 1 information

Column 2 informationColumn 2 information

Column 3 informationColumn 3 information

The ViaSQL SQLDA Structure

Same format as the DB2 SQLDA Partially filled in when DESCRIBE is executed Describes the columns to be processed by an RSP User must supply pointers to data and null indicators

DESCRIBE Processing

Makes RSP development easier The Legacy Data Manager is used to create a Virtual Table

definition At execution time, the RSP issues DESCRIBE command to fill in

the SQLDA

Stored Procedure Test Facility

Provides standalone test of RSP Invoked via CICS SPTEST command User specifies stored procedure name Variables can be specified Data and messages are displayed

More Information

Remote Stored Procedure Programmers Guide and Reference Sample RSPs on our website Sample RSPs distributed with ViaSQL software