Exploiting the EZASMI/EZASOKET Programming Interfaces
Applications on z/VSE can use the EZASMI
and / or EZASOKET programming interfaces. These programming interfaces
are provided both for programming in a batch environment and in a CICS® Transaction Server environment.
Following are a few sample programs that show a simple
usage of these interfaces. To reduce complexity they do not include
any error recovery necessary, if communication problems show up.
The first sample shows a client assembler program, which uses the
EZASMI macro interface: Figure 1. Sample
Program Using EZASMI Macro (Synchronously)
* PRINT NOGEN
***********************************************************************
* *
* MODULE NAME: SAMPCLIE *
* *
* FUNCTION: Sample program for usage of EZASMI macro *
* (Client part) *
* *
* ATTRIBUTES: NON-REUSABLE *
* *
* REGISTER USAGE: *
* R3 = BASE REG *
* R13 = SAVE AREA *
* *
* INPUT: NONE *
* OUTPUT: NONE *
* *
************************************************************************
---------------------------------------------------------------------*
* START OF EXECUTABLE CODE *
*---------------------------------------------------------------------*
SAMPCLIE START X'78' adjust addr behind part savearea
SAMPCLIE AMODE ANY
SAMPCLIE RMODE ANY
USING *,R15 Use Entry Register for base
B SAMPCLST
DC C'SAMPCLST-00/06/23'
*
SAMPCLST DS 0H
STM R14,R12,12(R13) Save Caller's Registers
LR R3,R15 Change base register to R3
DROP R15 Done with this register
USING SAMPCLIE,R3 Tell assembler about new base
LA R15,MYSAVE Get addr of own save area
ST R13,MYSAVE+4 Save caller's save area addr
ST R15,8(R13) Save own save area addr
LR R13,R15 Load Reg13
***********************************************************************
* *
* Issue INITAPI to connect to interface *
***********************************************************************
EZASMI TYPE=INITAPI, Issue INITAPI Macro X
MAXSOC=MAXSOC, Max number of sockets (in) X
MAXSNO=MAXSNO, Greatest Descr Number used (out)X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
***********************************************************************
* Issue SOCKET call *
***********************************************************************
EZASMI TYPE=SOCKET, Issue SOCKET call X
AF='INET', INTERNET family X
SOCTYPE='STREAM', Stream socket X
PROTO=PROTOCOL, protocol X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
MVC SOCKET1,RETCODE Save the socket descriptor
*
***********************************************************************
* Issue CONNECT *
***********************************************************************
EZASMI TYPE=CONNECT, Issue CONNECT call X
S=SOCKET1+2, socket descriptor (halfword) X
NAME=SAMPSERV, to SAMPSERV program X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
***********************************************************************
* Issue WRITE on connected socket *
***********************************************************************
EZASMI TYPE=WRITE, Issue WRITE call X
S=SOCKET1+2, on this socket X
NBYTE=MSG1L, Length of first message X
BUF=MSG1, Text of first message X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
B READ1 go and read
*
MSG1L DC F'40'
MSG1 DC CL40'DATA SENT FROM SAMPCLIE.'
***********************************************************************
* Issue READ on connected socket *
***********************************************************************
READ1 EZASMI TYPE=READ, Issue READ call X
S=SOCKET1+2, on this socket X
NBYTE=READBL, length of read buffer X
BUF=READB, address of read buffer X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
***********************************************************************
* Issue CLOSE on connected socket *
***********************************************************************
EZASMI TYPE=CLOSE, Issue CLOSE call X
S=SOCKET1+2, on this socket X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
***********************************************************************
* *
* Issue TERMAPI to disconnect interface *
***********************************************************************
EZASMI TYPE=TERMAPI Issue TERMAPI call
*
EOJ
EJECT
*---------------------------------------------------------------------*
* CONSTANTS/VARIABLES USED BY THIS PROGRAM *
*---------------------------------------------------------------------*
EZASMI TYPE=TASK,STORAGE=CSECT Task Storage Area
MYSAVE DC 18F'0' Register Save Area
ERRNO DC F'0'
RETCODE DC F'0'
*---------------------------------------------------------------------*
* INITAPI macro parms *
*---------------------*
MAXSOC DC H'256' MAXSOC parm value
MAXSNO DC F'0' Highest socket descriptor avail
*---------------------------------------------------------------------*
* SOCKET macro parms *
*--------------------*
PROTOCOL DC F'0' default protocol
SOCKET1 DC F'0' save area for socket descriptor
*
*---------------------------------------------------------------------*
* CONNECT Macro Parms*
*--------------------*
CNOP 0,4
SAMPSERV DC 0CL16' ' SOCKET NAME structure of SERVER
DC AL2(2) FAMILY (AF-INET)
DC H'4000' Port of SAMPSERV
DC AL1(9),AL1(164),AL1(155),AL1(122) IP-Addr of SAMPSERV
DC XL8'00' RESERVED
*
*---------------------------------------------------------------------*
* READ MACRO PARMS *
*--------------------*
READBL DC F'40' SIZE OF READ BUFFER
READB DC CL40' ' READ BUFFER
**---- register equates ----------------------------------------------*
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
*
END SAMPCLIE
The second sample shows a server assembler program using
the asynchronous EZASMI macro interface: Figure 2. Sample Program Using EZASMI Macro (Asynchronously)
* PRINT NOGEN
***********************************************************************
* *
* MODULE NAME: SAMPSERV *
* *
* FUNCTION: Sample Program for EZASMI (asynchronous) macro usage *
* (Server Part) *
* *
* ATTRIBUTES: NON-REUSABLE *
* NON-LE Enabled *
* *
* REGISTER USAGE: *
* R3 = BASE REG 1 *
* R13 = SAVE AREA *
* *
* INPUT: NONE *
* OUTPUT: NONE *
* *
***********************************************************************
*---------------------------------------------------------------------*
* START OF EXECUTABLE CODE *
*---------------------------------------------------------------------*
SAMPSERV START X'78' adjust addr behind part savearea
SAMPSERV AMODE 31
SAMPSERV RMODE ANY
USING *,R15 Use Entry Register for base
B SAMPSTRT
DC C'SAMPSEST-00/06/23'
*
SAMPSTRT DS 0H
STM R14,R12,12(R13) Save Caller's Registers
LR R3,R15 Change base register to R3
DROP R15 Done with this register
USING SAMPSERV,R3 Tell assembler about new base
LA R15,MYSAVE Get addr of own save area
ST R13,MYSAVE+4 Save caller's save area addr
ST R15,8(R13) Save own save area addr
LR R13,R15 Load Reg13
***********************************************************************
* Issue INITAPI to connect to interface *
***********************************************************************
EZASMI TYPE=INITAPI, Issue INITAPI Macro X
MAXSOC=MAXSOC, Max number of sockets (in) X
MAXSNO=MAXSNO, Greatest Descr Number used (out)X
ASYNC='ECB', asynchronous ECB processing X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
***********************************************************************
* Issue SOCKET call *
***********************************************************************
XC ECB,ECB
EZASMI TYPE=SOCKET, Issue SOCKET call X
AF='INET', INTERNET family X
SOCTYPE='STREAM', Stream socket X
PROTO=PROTOCOL, protocol X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
MVC SOCKET1,RETCODE Save the socket descriptor
***********************************************************************
* Issue BIND call *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=BIND, Issue BIND call X
S=SOCKET1+2, socket descriptor X
NAME=MYNAME, Name structure X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
***********************************************************************
* Issue LISTEN *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=LISTEN, Issue LISTEN call X
S=SOCKET1+2, socket descriptor X
BACKLOG=BACKLOG, max number of backlog msgs X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
***********************************************************************
* Issue ACCEPT *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=ACCEPT, Issue ACCEPT call X
S=SOCKET1+2, socket descriptor X
NAME=NAMECLIE, Name structure of client X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
MVC SOCKETN,RETCODE Save RETCODE (New Socket Descr.)
***********************************************************************
* Issue READ *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=READ, Issue READ call X
S=SOCKETN+2, on this socket X
NBYTE=READBUFL, length of read buffer X
BUF=READBUF, address of read buffer X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
***********************************************************************
* Issue WRITE on connected socket *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=WRITE, Issue WRITE call X
S=SOCKETN+2, on this socket X
NBYTE=MSGL, Length of first message X
BUF=MSG, Text of first message X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
B CLOSE1
*
MSGL DC F'40'
MSG DC CL40'SAMPSERV RECEIVED YOUR DATA.'
***********************************************************************
* Issue CLOSE socket *
***********************************************************************
CLOSE1 XC ECB,ECB Clear ECB
EZASMI TYPE=CLOSE, Issue CLOSE call X
S=SOCKETN+2, on this socket X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
***********************************************************************
* Issue CLOSE socket *
***********************************************************************
XC ECB,ECB Clear ECB
EZASMI TYPE=CLOSE, Issue CLOSE call X
S=SOCKET1+2, on this socket X
ECB=*ECBA, wait on this ECB X
ERRNO=ERRNO, ERRNO field X
RETCODE=RETCODE RETCODE field
*
WAIT ECB Wait on ECB
***********************************************************************
* Issue TERMAPI to disconnect interface *
***********************************************************************
EZASMI TYPE=TERMAPI Issue TERMAPI Call
EOJ
EJECT
*---------------------------------------------------------------------*
* CONSTANTS/VARIABLES USED BY THIS PROGRAM *
*---------------------------------------------------------------------*
EZASMI TYPE=TASK,STORAGE=CSECT Task Storage Area
MYSAVE DC 18F'0' Register Save Area
ERRNO DC F'0'
RETCODE DC F'0'
ECBA DC A(ECB) POINTER to ECB
ECB DC F'0' ECB
ECBX DC XL156'00' ECB Extension Area
*
*---------------------------------------------------------------------*
* INITAPI macro parms *
*---------------------*
MAXSOC DC H'80' MAXSOC PARM VALUE
MAXSNO DC F'0' Highest Socket Descriptor avail
*
*---------------------------------------------------------------------*
* SOCKET macro parms *
*--------------------*
PROTOCOL DC F'0' default protocol
SOCKET1 DC F'0' savearea for socket descriptor
SOCKETN DC F'0' savearea for socket descriptor
*
*---------------------------------------------------------------------*
* BIND MACRO PARMS *
*--------------------*
CNOP 0,4
MYNAME DC 0CL16' ' SOCKET NAME STRUCTURE
DC AL2(2) FAMILY (AF-INET)
MYPORT DC H'4000' bind to this port
MYADDR DC AL1(9),AL1(164),AL1(155),AL1(122) and IP address
DC XL8'00' RESERVED
*---------------------------------------------------------------------*
* LISTEN PARMS *
*--------------------*
BACKLOG DC F'5' BACKLOG
*---------------------------------------------------------------------*
* ACCEPT PARMS *
*--------------------*
NAMECLIE DC 0CL16' ' SOCKET NAME STRUCTURE of client
DC AL2(2) FAMILY
PORTCLIE DC H'0'
ADDRCLIE DC F'0'
DC XL8'00' RESERVED
*---------------------------------------------------------------------*
* READ MACRO PARMS *
*--------------------*
READBUFL DC F'40' SIZE OF READ BUFFER
READBUF DC CL40'none' READ BUFFER
* ------ register equates --------------------------------------------
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
*
END SAMPSERV
Of course, there is no real need
for this simple program to use the asynchronous interface. Asynchronous
processing can be helpful, if the program wants to perform other tasks
while waiting on a socket call to complete.
The next sample shows a similar server program written
in COBOL using the EZASOKET call interface: Figure 3. Sample Program Using EZASOKET Call Using COBOL
CBL LIB APOST RMODE(ANY) SAM00010
IDENTIFICATION DIVISION. SAM00020
SAM00030
PROGRAM-ID. SAMPSERV SAM00040
AUTHOR. HEINZ HAGEDORN SAM00050
INSTALLATION. HIER. SAM00060
DATE-WRITTEN. June 23, 2000 SAM00070
DATE-COMPILED. SAM00080
SAM00090
ENVIRONMENT DIVISION. SAM00100
SAM00110
CONFIGURATION SECTION. SAM00120
SAM00130
SOURCE-COMPUTER. IBM-370. SAM00140
OBJECT-COMPUTER. IBM-370. SAM00150
SAM00160
DATA DIVISION. SAM00170
SAM00180
SAM00190
WORKING-STORAGE SECTION. SAM00200
01 SOKET-FUNCTIONS. SAM00210
02 SOKET-ACCEPT PIC X(16) VALUE 'ACCEPT '. SAM00220
02 SOKET-BIND PIC X(16) VALUE 'BIND '. SAM00230
02 SOKET-CLOSE PIC X(16) VALUE 'CLOSE '. SAM00240
02 SOKET-CONNECT PIC X(16) VALUE 'CONNECT '. SAM00250
02 SOKET-INITAPI PIC X(16) VALUE 'INITAPI '. SAM00260
02 SOKET-LISTEN PIC X(16) VALUE 'LISTEN '. SAM00270
02 SOKET-READ PIC X(16) VALUE 'READ '. SAM00280
02 SOKET-SOCKET PIC X(16) VALUE 'SOCKET '. SAM00290
02 SOKET-TERMAPI PIC X(16) VALUE 'TERMAPI '. SAM00300
02 SOKET-WRITE PIC X(16) VALUE 'WRITE '. SAM00310
01 SOKET-FUNCT PIC X(16) VALUE ' '. SAM00320
01 SOKET-ADDR. SAM00330
02 SOCK-FAMILY PIC 9(4) BINARY. SAM00340
02 SOCK-PORT PIC 9(4) BINARY. SAM00350
02 SOCK-IPADDR PIC 9(8) BINARY. SAM00360
02 SOCK-ZERO PIC X(8). SAM00370
01 SOKET-ID PIC 9(4) BINARY. SAM00380
01 SOKET-ID-NEW PIC 9(4) BINARY. SAM00390
01 MAXSOC PIC 9(4) BINARY. SAM00400
01 IDENT. SAM00410
02 TCPNAME PIC X(8). SAM00420
02 ADSNAME PIC X(8). SAM00430
01 SUBTASK PIC X(8). SAM00440
01 MAXSNO PIC 9(8) BINARY. SAM00450
SAM00460
01 INBUFFL PIC 9(8) COMP VALUE 40. SAM00570
SAM00580
01 AF-INET PIC 9(8) COMP VALUE 2. SAM00470
01 SOCTYPE PIC 9(8) COMP VALUE 1. SAM00480
01 PROTO PIC 9(8) COMP VALUE 0. SAM00490
01 BACKLOG PIC 9(8) COMP VALUE 5. SAM00500
01 RETCODE PIC S9(8) BINARY. SAM00510
01 ERRNO PIC 9(8) BINARY. SAM00520
01 MSG001 PIC X(34) SAM00530
VALUE IS ' ... SAMPSERV received your data.'. SAM00540
01 MSG001L PIC 9(8) COMP VALUE 34. SAM00550
01 INBUFF PIC X(40) VALUE IS ' '. SAM00560
PROCEDURE DIVISION. SAM00590
SAM00600
BEGIN. SAM00610
SAM00620
*----------------------------------------------* SAM00630
* CALL EZASOKET - function = INITAPI * SAM00640
* input = SUBTASK blank * SAM00650
*----------------------------------------------* SAM00660
SAM00670
MOVE SOKET-INITAPI TO SOKET-FUNCT. SAM00680
MOVE ' ' TO TCPNAME. SAM00690
MOVE ' ' TO SUBTASK. SAM00700
MOVE 99 TO MAXSOC. SAM00710
MOVE 0 TO RETCODE. SAM00720
MOVE 0 TO ERRNO. SAM00730
SAM00740
CALL 'EZASOKET' USING SOKET-FUNCT MAXSOC IDENT SUBTASK SAM00750
MAXSNO ERRNO RETCODE. SAM00760
SAM00770
*-------------------------------------------* SAM00780
* CALL EZASOKET - function = SOCKET * SAM00790
*-------------------------------------------* SAM00800
SAM00810
MOVE SOKET-SOCKET TO SOKET-FUNCT. SAM00820
MOVE 0 TO RETCODE. SAM00830
MOVE 0 TO ERRNO. SAM00840
SAM00850
CALL 'EZASOKET' USING SOKET-FUNCT AF-INET SOCTYPE PROTO SAM00860
ERRNO RETCODE. SAM00870
SAM00880
MOVE RETCODE TO SOKET-ID. SAM00890
SAM00900
*---------------------------------------------------- * SAM00910
* CALL EZASOKET - function = BIND * SAM00920
* input = Soket-id, Soket-addr * SAM00930
*-----------------------------------------------------* SAM00940
SAM00950
MOVE SOKET-BIND TO SOKET-FUNCT. SAM00960
MOVE AF-INET TO SOCK-FAMILY. SAM00970
MOVE 4000 TO SOCK-PORT. SAM00980
MOVE 0 TO SOCK-IPADDR. SAM00990
MOVE 0 TO RETCODE. SAM01000
MOVE 0 TO ERRNO. SAM01010
SAM01020
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID SOKET-ADDR SAM01030
ERRNO RETCODE. SAM01040
SAM01050
SAM01060
*------------------------------------------------------* SAM01070
* CALL EZASOKET - function = LISTEN * SAM01080
* input = backlog=5 * SAM01090
*------------------------------------------------------* SAM01100
SAM01110
MOVE SOKET-LISTEN TO SOKET-FUNCT. SAM01120
MOVE 0 TO RETCODE. SAM01130
MOVE 0 TO ERRNO. SAM01140
SAM01150
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID BACKLOG SAM01160
ERRNO RETCODE. SAM01170
SAM01180
SAM01190
*-------------------------------------------* SAM01200
* CALL EZASOKET - function = ACCEPT * SAM01210
* input = SOKET-ID * SAM01220
*-------------------------------------------* SAM01230
SAM01240
MOVE SOKET-ACCEPT TO SOKET-FUNCT. SAM01250
MOVE 0 TO RETCODE. SAM01260
MOVE 0 TO ERRNO. SAM01270
SAM01280
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID SOKET-ADDR SAM01290
ERRNO RETCODE. SAM01300
SAM01310
MOVE RETCODE TO SOKET-ID-NEW. SAM01320
SAM01330
*------------------------------------------------------* SAM01340
* CALL EZASOKET - function = READ * SAM01350
*------------------------------------------------------* SAM01360
SAM01370
MOVE SOKET-READ TO SOKET-FUNCT. SAM01380
MOVE 0 TO RETCODE. SAM01390
MOVE 0 TO ERRNO. SAM01400
SAM01410
MOVE LOW-VALUES TO INBUFF. SAM01420
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID-NEW INBUFFL SAM01430
INBUFF ERRNO RETCODE. SAM01440
SAM01450
*------------------------------------------------------* SAM01460
* CALL EZASOKET - function = WRITE * SAM01470
*------------------------------------------------------* SAM01480
SAM01490
MOVE SOKET-WRITE TO SOKET-FUNCT. SAM01500
MOVE 0 TO RETCODE. SAM01510
MOVE 0 TO ERRNO. SAM01520
SAM01530
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID-NEW MSG001L SAM01540
MSG001 ERRNO RETCODE. SAM01550
SAM01560
*------------------------------------------------------* SAM01570
* CALL EZASOKET - function = CLOSE * SAM01580
*------------------------------------------------------* SAM01590
SAM01600
MOVE SOKET-CLOSE TO SOKET-FUNCT. SAM01610
MOVE 0 TO RETCODE. SAM01620
MOVE 0 TO ERRNO. SAM01630
SAM01640
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID-NEW SAM01650
ERRNO RETCODE. SAM01660
SAM01670
*------------------------------------------------------* SAM01680
* CALL EZASOKET - function = CLOSE * SAM01690
*------------------------------------------------------* SAM01700
SAM01710
MOVE SOKET-CLOSE TO SOKET-FUNCT. SAM01720
MOVE 0 TO RETCODE. SAM01730
MOVE 0 TO ERRNO. SAM01740
SAM01750
CALL 'EZASOKET' USING SOKET-FUNCT SOKET-ID SAM01760
ERRNO RETCODE. SAM01770
SAM01780
SAM01790
*------------------------------------------------------* SAM01800
* CALL EZASOKET - function = TERMAPI * SAM01810
*------------------------------------------------------* SAM01820
SAM01830
MOVE SOKET-TERMAPI TO SOKET-FUNCT. SAM01840
SAM01850
CALL 'EZASOKET' USING SOKET-FUNCT. SAM01860
SAM01870
SAM01880
STOP RUN. SAM01890
SAM01900
END PROGRAM SAMPSERV. SAM01910