DSN8CA
FUNCTION = PROVIDE AN EXAMPLE ASSEMBLER INTERFACE TO THE CALL ATTACH FACILITY.
TITLE 'DSN8CA (SAMPLE CAF ASSEMBLER INTERFACE)'
**********************************************************************
* *
* MODULE NAME = DSN8CA *
* *
* DESCRIPTIVE *
* NAME = SAMPLE CALL ATTACH FACILITY ASSEMBLER *
* INTERFACE *
* *
* COPYRIGHT = 5635-DB2 (C) COPYRIGHT IBM CORP 1982, 2006 *
* *
* STATUS = VERSION 9 *
* *
* FUNCTION = PROVIDE AN EXAMPLE ASSEMBLER INTERFACE TO THE *
* CALL ATTACH FACILITY. THIS PERMITS COBOL AND *
* PL/I PROGRAMS TO USE THE CALL ATTACH FACILITY TO *
* ESTABLISH THE CONNECTION TO DB2. *
* *
* THE FOLLOWING SERVICE REQUESTS WILL BE MADE TO *
* THE CALL ATTACH FACILITY. ISPF VARIABLES ARE USED *
* TO CONTAIN POINTERS TO ECBS AND CONTROL BLOCKS. *
* *
* - CONNECT *
* *
* ESTABLISH A CONNECTION BETWEEN AN APPLICATION'S *
* ADDRESS SPACE AND A SPECIFIED DB2 SUBSYSTEM. *
* *
* - OPEN *
* *
* ESTABLISH THE SPECIFIED PLAN AS A USER OF DB2 *
* SERVICES AND ALLOCATE RESOURCES FOR SQL CALLS. *
* THIS CAN BE CALLED 'CREATING A THREAD'. *
* *
* - CLOSE *
* *
* TERMINATE THE CURRENT THREAD USING THE *
* SPECIFIED TERMINATION OPTION. *
* *
* - DISCONNECT *
* *
* TERMINATE THE CONNECTION TO DB2. *
* *
* - TRANSLATE *
* *
* CLARIFIES A RESOURCE UNAVAILABLE CONDITION. *
* IT IS PERFORMED AFTER AN OPEN FAILURE. *
* *
* *
* INPUT = NONE *
* *
* OUTPUT = NONE *
* *
* NOTES = *
* *
* DEPENDENCIES = NONE *
* *
* RESTRICTIONS = NONE *
* *
* REGISTER *
* CONVENTIONS = *
* *
* REGISTER R0 IS SHORT TERM TEMPORARY *
* REGISTER R1 IS SHORT TERM TEMPORARY *
* REGISTER R2 IS SIZE OF THE PROGRAM AREA *
* REGISTER R3 IS THE ADDRESS OF THE GETMAINED AREA *
* REGISTER R4 IS A WORK REGISTER *
* REGISTER R5 IS A WORK REGISTER *
* REGISTER R6 IS A WORK REGISTER *
* REGISTER R7 IS A WORK REGISTER *
* REGISTER R8 IS A WORK REGISTER *
* REGISTER R9 IS A WORK REGISTER *
* REGISTER R11 IS ADDRESS OF THE PROGRAM STORAGE *
* REGISTER R12 IS THE BASE REGISTER, -> DSN8CA *
* REGISTER R13 IS THE SAVEAREA, WORKAREA POINTER *
* REGISTER R14 IS SHORT TERM TEMPORARY *
* REGISTER R15 IS SHORT TERM TEMPORARY *
* *
* MODULE TYPE = PROCEDURE *
* *
* PROCESSOR = ASSEMBLER XF OR H *
* *
* MODULE *
* SIZE = 250 LOC *
* *
* ATTRIBUTES = REENTERABLE *
* *
* ENTRY POINT = DSN8CA *
* *
* PURPOSE = SEE FUNCTION *
* *
* LINKAGE = CALL DSN8CA. *
* *
* INPUT = ISPF SERVICES ARE USED TO OBTAIN INFORMATION *
* FROM THE MAIN PANEL AND THE CONNECTION MANAGER. *
* THE FOLLOWING INFORMATION IS RETRIEVED: *
* *
* FUNCTION (12 CHARACTERS) *
* *
* CONNECT: *
* *
* SUBSYSTEM ID ( 4 CHARACTERS) *
* *
* OPEN: *
* *
* SUBSYSTEM ID ( 4 CHARACTERS) *
* PROGRAM NAME ( 8 CHARACTERS) *
* PLAN NAME ( 8 CHARACTERS) *
* *
* CLOSE: *
* *
* TERM-OPTION ( 4 CHARACTERS) *
* *
* DISCONNECT: *
* *
* NO PARAMETERS *
* *
* TRANSLATE: *
* *
* SQLCA (136 BYTES ) *
* *
* *
* OUTPUT = PARAMETERS EXPLICITLY RETURNED: *
* *
* REASCODE *
* ISPF VARIABLE NAME : DSN8REAS *
* *
* EXIT-NORMAL = THE REQUESTED FUNCTION WAS PERFORMED SUCCESSFULLY *
* *
* EXIT-ERROR = THE REQUESTED FUNCTION WAS NOT PERFORMED *
* *
* *
* ABEND *
* CODES = NONE *
* *
* ERROR *
* MESSAGES = NONE *
* *
* EXTERNAL *
* REFERENCES = *
* ROUTINES/ *
* SERVICES = DSNALI - CALL ATTACH LANGUAGE INTERFACE *
* ISPLINK - ISPF SERVICES *
* *
* DATA-AREAS = NONE *
* *
* CONTROL *
* BLOCKS = NONE *
* *
* MACROS CALL - INVOKE A ROUTINE *
* DSNTIACN - REGISTER DEFINITIONS *
* FREEMAIN - FREE MAIN STORAGE *
* GETMAIN - GET MAIN STORAGE *
* RETURN - RETURN TO THE INVOKER *
* SAVE - SAVE CALLER'S REGISTERS *
* *
* TABLES = LOCAL TABLES AND WORK AREAS USED: *
* *
* CHANGE *
* ACTIVITY = NONE *
* *
* PSEUDOCODE = *
* *
* SELECT (FUNCTION) /* Which function requested? */ *
* WHEN ('CONNECT ') /* Connect */ *
* DO *
* SET UP PARMS *
* ISSUE 'CONNECT' CALL /* Establish DB2 connection */ *
* END *
* WHEN ('OPEN ') /* Open */ *
* DO *
* SET UP PARMS *
* ISSUE 'OPEN' CALL /* Create thread for appl */ *
* END *
* WHEN ('CLOSE ') /* Close */ *
* DO *
* SET UP PARMS *
* ISSUE 'CLOSE' CALL /* Terminate thread for appl */ *
* END *
* WHEN ('DISCONNECT ') /* Disconnect */ *
* DO *
* SET UP PARMS *
* ISSUE 'DISCONNECT' CALL /* Disconnect from DB2 */ *
* END *
* WHEN ('TRANSLATE ') /* Translate */ *
* DO *
* SET UP PARMS *
* ISSUE 'TRANSLATE' CALL /* Clarifies open errors */ *
* END *
* OTHERWISE /* Invalid service request */ *
* DO *
* INVALID FUNCTION REQUESTED *
* END *
* END /* End select */ *
* IF RETURN CODE ^= 0 THEN /* Bad return code */ *
* CONVERT REASON CODE TO PRINTABLE CHARACTERS *
* EXIT *
* *
**********************************************************************
DSNTIACN
**********************************************************************
* HOUSEKEEPING *
**********************************************************************
DSN8CA AMODE 31 Address in 31 bits
DSN8CA RMODE ANY Reside anywhere
DSN8CA CSECT CONTROL SECTION NAME
SAVE (14,12),,* SAVE REGISTERS
LR R12,R15 ESTABLISH ADDRESSABILITY
USING DSN8CA,R12 USING THE ADDRESS OF THE CSECT
L R2,PGMSIZ SIZE OF THE USER PROGRAM
GETMAIN R,LV=(2) GET STORAGE FOR PROGRAM VARIABLES
LR R3,R1 SAVE ADDRESS FOR FREEMAIN
LR R11,R1 R11 CONTAINS ADDRESS OF STORAGE
USING PGMAREA,R11 ESTABLISH DATA AREA ADDRESSABILITY
LA R15,SAVEAREA GET ADDRESS OF CSECT'S SAVE AREA
ST R13,FOUR(R15) CHAIN THE SAVE AREA BACK POINTER
ST R15,EIGHT(R13) CHAIN SAVEAREA FORWARD
LR R13,R15 ADDRESS OF CSECT'S SAVE AREA
**********************************************************************
* INITIALIZE WORK REGISTERS *
**********************************************************************
SR R4,R4 CLEAR THE WORK REGISTERS
SR R5,R5
SR R6,R6
SR R7,R7
SR R8,R8
SR R9,R9
EJECT
**********************************************************************
* DECLARATIONS FOR THE ISPF VARIABLES TO BE USED IN THIS PROGRAM *
**********************************************************************
CALL ISPLINK,(VDEFINE,NAMEACTN,FUNCTION,CHAR,FIX12),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMESSID,SSID,CHAR,FIX4),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMETECB,TECB,FIXED,FIX4),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMESECB,SECB,FIXED,FIX4),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMEPLAN,PLAN,CHAR,FIX8),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMETERM,TERMOP,CHAR,FIX4),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMESQCA,SQLCA,CHAR,FIXCA),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VDEFINE,NAMESERV,FUNCTION,CHAR,FIX12),VL, X
MF=(E,CALLPA)
**********************************************************************
* RETRIEVE THE SERVICE REQUEST *
**********************************************************************
CALL ISPLINK,(VGET,NAMEACTN),VL,MF=(E,CALLPA)
**********************************************************************
* CONNECT *
**********************************************************************
CONNREQ DS 0H
CLC FUNCTION,CONNECT HAS CONNECT BEEN REQUESTED?
BNE OPENREQ IF NOT, CHECK OPEN
CALL ISPLINK,(VGET,NAMESSID),VL,MF=(E,CALLPA)
CALL ISPLINK,(VGET,NAMETECB),VL,MF=(E,CALLPA)
CALL ISPLINK,(VGET,NAMESECB),VL,MF=(E,CALLPA)
LA R5,SSID SUBSYSTEM NAME
LA R6,TECB START ECB
LA R7,SECB TERMINATION ECB
LA R8,RIBPTR RELEASE INFORMATION BLOCK
MVC CALLPA(CAFLEN),CAFCALL
CALL DSNALI,(CONNECT,(R5),(R6),(R7),(R8)),VL,MF=(E,CALLPA)
B ENDSEL
**********************************************************************
* OPEN *
**********************************************************************
OPENREQ DS 0H
CLC FUNCTION,OPEN HAS OPEN BEEN REQUESTED?
BNE CLOSEREQ IF NOT, CHECK CLOSE
CALL ISPLINK,(VGET,NAMESSID),VL,MF=(E,CALLPA)
CALL ISPLINK,(VGET,NAMEPLAN),VL,MF=(E,CALLPA)
LA R5,SSID SUBSYSTEM NAME
LA R6,PLAN PLAN NAME
MVC CALLPA(CAFLEN),CAFCALL
CALL DSNALI,(OPEN,(5),(6)),VL,MF=(E,CALLPA)
B ENDSEL
**********************************************************************
* CLOSE *
**********************************************************************
CLOSEREQ DS 0H
CLC FUNCTION,CLOSE HAS CLOSE BEEN REQUESTED?
BNE DISCREQ IF NOT, CHECK DISCONNECT
CALL ISPLINK,(VGET,NAMETERM),VL,MF=(E,CALLPA)
LA R5,TERMOP TERMINATION OPTION
MVC CALLPA(CAFLEN),CAFCALL
CALL DSNALI,(CLOSE,(5)),VL,MF=(E,CALLPA)
B ENDSEL
**********************************************************************
* DISCONNECT *
**********************************************************************
DISCREQ DS 0H
CLC FUNCTION,DISC HAS DISCONNECT BEEN REQUESTED
BNE XLATEREQ IF NOT, CHECK TRANSLATE
MVC CALLPA(CAFLEN),CAFCALL
CALL DSNALI,(DISC),VL,MF=(E,CALLPA)
B ENDSEL
**********************************************************************
* TRANSLATE *
**********************************************************************
XLATEREQ DS 0H
CLC FUNCTION,XLATE HAS TRANSLATE BEEN REQUESTED
BNE FNERROR IF NOT, CHECK DISCONNECT
CALL ISPLINK,(VGET,NAMESQCA),VL,MF=(E,CALLPA)
LA R5,SQLCA SQL COMMUNICATION AREA
MVC CALLPA(CAFLEN),CAFCALL
CALL DSNALI,(XLATE,(5)),VL,MF=(E,CALLPA)
CALL ISPLINK,(VPUT,NAMESQCA),VL,MF=(E,CALLPA)
B ENDSEL
**********************************************************************
* INVALID FUNCTION REQUEST *
**********************************************************************
FNERROR DS 0H
CALL ISPLINK,(VPUT,NAMESERV),VL,MF=(E,CALLPA)
LA R15,11 INVALID FUNCTION REQUEST RETURN CODE
LR R9,R15
B EXIT
**********************************************************************
* HANDLE THE REASON CODE *
**********************************************************************
ENDSEL DS 0H
ST R0,PACKCODE STORE THE REASON CODE
LR R9,R15 STORE THE RETURN CODE
UNPK REASCODE(NINE),PACKCODE(FIVE)
TR REASCODE(EIGHT),XTAB
CALL ISPLINK,(VDEFINE,NAMEFAIL,REASCODE,CHAR,FIX8),VL, X
MF=(E,CALLPA)
CALL ISPLINK,(VPUT,NAMEFAIL),VL,MF=(E,CALLPA)
**********************************************************************
* DELETE ISPF VARIABLES *
**********************************************************************
CALL ISPLINK,(VDELETE,NAMEFAIL),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMEACTN),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMESSID),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMETECB),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMESECB),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMEPLAN),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMETERM),VL,MF=(E,CALLPA)
CALL ISPLINK,(VDELETE,NAMESQCA),VL,MF=(E,CALLPA)
**********************************************************************
* FREE THE STORAGE USED BY THIS PROGRAM *
**********************************************************************
EXIT DS 0H
L R13,4(R13) ADDRESS OF THE CALLER'S SAVE AREA
L R0,PGMSIZ THE SIZE OF THE GETMAINED STORAGE
LR R1,R3 R1 CONTAINS THE STORAGE ADDRESS
FREEMAIN R,LV=(0),A=(1) FREE THE GOTTEN STORAGE
LR R15,R9 PUT THE RETURN CODE IN R15
RETURN (14,12),T,RC=(15) AND RETURN
**********************************************************************
* PROGRAM CONSTANTS DECLARATIONS *
**********************************************************************
CAFCALL CALL ,(*,*,*,*,*),VL,MF=L
CAFLEN EQU *-CAFCALL
FIX4 DC F'4' USED FOR LENGTH
FIX8 DC F'8' USED FOR LENGTH
FIX12 DC F'12' USED FOR LENGTH
FIXCA DC F'136' LENGTH OF THE SQLCA
XTAB DC XL240'00' TRANSLATE TABLE FOR BINARY TO HEX
DC C'0123456789ABCDEF'
**********************************************************************
* CALL ATTACH FUNCTION REQUEST NAMES *
**********************************************************************
CONNECT DC CL12'CONNECT ' CONNECT TO DB2
OPEN DC CL12'OPEN ' OPEN (CREATE THREAD)
CLOSE DC CL12'CLOSE ' CLOSE (TERMINATE THREAD)
DISC DC CL12'DISCONNECT ' DISCONNECT FROM DB2
XLATE DC CL12'TRANSLATE ' TRANSLATE OPEN ERRORS
**********************************************************************
* ISPF FUNCTION NAMES *
**********************************************************************
VDEFINE DC CL8'VDEFINE ' DEFINE A VARIABLE
VDELETE DC CL8'VDELETE ' DELETE A VARIABLE
VGET DC CL8'VGET ' RETRIEVE A VALUE FROM THE SHARED POOL
VPUT DC CL8'VPUT ' PLACE A VAULE IN THE SHARED POOL
CHAR DC CL8'CHAR ' CHARACTER DATA TYPE
FIXED DC CL8'FIXED ' FIXED DATA TYPE
SHARED DC CL8'SHARED ' VARIABLES IN SHARED POOL
NAMEFAIL DC CL8'DSN8REAS' REASON CODE RETURNED FROM CAF
NAMESQCA DC CL8'DSN8SQCA' SQLCA
NAMETECB DC CL8'DSN8TECB' TERMINATION ECB
NAMESECB DC CL8'DSN8SECB' START ECB
NAMETERM DC CL8'DSN8TERM' TERMINATION OPTION
NAMEPLAN DC CL8'DSN8PLAN' PLAN TO BE OPENED
NAMESSID DC CL8'DSN8SSID' SUBSYSTEM NAME
NAMEACTN DC CL8'DSN8ACTN' SERVICE TO BE PERFORMED
NAMESERV DC CL8'DSN8SERV' SERVICE TO BE PERFORMED
PGMSIZ DC A(PGMSIZE) AMOUNT OF WORKING STORAGE NEEDED
**********************************************************************
* WORKING STORAGE AREA *
**********************************************************************
PGMAREA DSECT
SAVEAREA DS 18F SAVE AREA FOR DSN8CA
LIALI DS F CALL ATTACH INTERFACE
CALLPA DS 0F CALL PARAMETER AREA
CALL ,(*,*,*,*,*),VL,MF=L
PACKCODE DC CL5' ' REASON CODE FROM HERE
REASCODE DC CL9' ' READABLE RETURN CODE (HEX)
FUNCTION DS CL12 CALL ATTACH SERVICE REQUESTED
SSID DS CL4' ' SUBSYSTEM NAME
TECB DS F TERMINATION ECB
SECB DS F START ECB
RIBPTR DS F RELEASE INFORMATION BLOCK
PLAN DC CL8' ' PLAN NAME
TERMOP DC CL4' ' TERMINATION OPTION
EXEC SQL INCLUDE SQLCA
DS 0D
PGMSIZE EQU *-PGMAREA WORKING STORAGE SIZE CALCULATION
END DSN8CA