IOERROR XI 80 1 (Error not
Chapter 3.3. DLtI Services
The CICS/VS application programmer can request Oata Language/I ~L/I)
services in two ways:
1. By issuing a OL/I CALL statement, written according to OL/I specifications. This method is available to both CICS/OS/VS and CICS/OOS/VS users. This OL/I CALL is mandatory if the user wishes to access remote OL/I data bases using ISC.
2. By issuing a OFHFC macro instruction. This method is available to CICS/OS/VS users only.
In both cases, control is passed to a routine that acts as an
interface between the CICS/VS application program and the OL/I request handler. This routine performs validity checks on the CALL l i s t , prepares OL/I to handle the request, and passes control and the CALL l i s t to OL/I. After OL/I has handled the request, i t returns control to the calling program unless a OL/I pseudo-abend has occurred, in which case the CICS/VS task is abnormally terminated.
Under CICS/VS, two or more transactions (tasks) may require the same application program at any given time during system operation. Because CICS/VS application programs must be qreenterable (see IIQ uasi-Reenterability," in Chapter 1.1), OL/I areas that may be modified under CICSjOS/VS (such as PCB pointers, I/O work areas, and segment search arguments) should not be placed in static storage. They should also not be placed in working storage (unless the application program contains one or more command-level statements, in which case working storage is dynamic). Storage for such areas must be obtained from CICS/VS dynamic storage by each transaction using the program.
Four steps must be performed by an application program requesting OL/I data base services. These steps are listed below and explained in the sections that follow.
1. Obtain addresses of program communication blocks (PCBs) to be used by the application program.
2. Building segment search arguments (SSAs) if they are to be used in the CALL.
3. Acquire I/O work areas for OL/I segments processed by the program.
4. Issue the OL/I CALL.
Obtaining Addresses of Program Communication Blocks
An application program that uses the CICS/VS-OL/I interface accesses data bases by means of program communication blocks (PCBs). One PCB for each data base is included in the program specification block (PSB) for the program. To process OL/I CALLs within a CICS/VS transaction, the PSB for the transaction must be scheduled and the PCB addresses obtained before any OL/I CALLs are made. Scheduling involves, for example, that all the required OL/I control blocks exist and are in main storage, and that the processing options associated with this PSB permit i t to be scheduled concurrently with those PSBs already scheduled. If they are not obtained, an INVREQ (invalid request) indicator is returned in response to any OL/I CALL within the program.
Chapter 3.3. OL/I Services 135
A transaction may schedule only one PSB at a time. An attempt to schedule a second PSB while one is still scheduled causes the INVREQ indicator to be returned.
A sync point request (refer to the DFHSP macro instruction in Chapter 7.5) by a task that is scheduled to use DL/I resources implies the
release of those resources. This means that if, after issuing a DFHSP TYPE=USER macro instruction, access to a DL/I data base is required, the desired PSB must be rescheduled. The previous position of that data base has been lost.
I/O PCBs (a type of control block used by I"S/VS) are not passed to CICS/VS programs, even though they may be included in a transaction's PSB, either explicitly or implicitly by means of the COMPAT=YES option.
DFHFC MACRO INSTRUCTION (CICS/OS/VS ONLY)
To schedule the desired PSB and obtain PCB addresses, the CICS/OS/VS application programmer may use a special form of the DFHFC macro instruction:
r---~---·r---,
I I I I I I I I I I
DFHFC TYPE=~L/I,PCB)
[,PSB={'psbname'lsymbolic addressIYES}]
[,NORESP=symbolic address]
[,DLINA=symbolic address]
[,PSBSCH=symbolic address]
[,PSBNF=symbolic address]
[,PSBFAIL=symbolic address]
[,INVREQ=symbolic address]
L _______ ~ _______ ~ ________________________________________________________ ~
where:
TYPE=(DL/I,PCB)
indicates that PCB addresses are to be acquired.
~: DL/I in the TYPE= operand may also be coded as DLI or DL1.
If the PSB has been located, TCADLPCB contains the address of a list of PCB addresses in the sequence in which the PCB addresses were
specified during the PSBGEN of this PSB. If the PSB cannot be found, TCADLPCB contains zero. If the PSB pool or DMB pool is too small to hold the requested blocks even when no other PSBs or DMBs are in their pools, the transaction is terminated with the ADLA ABEND code.
136 CICS/VS APRM(ML)
DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS)
Upon receiving control from CICS/VS, a CICS/VS application program must issue a DL/I call to perform scheduling before attempting to access DL/I data bases. If the scheduling call is successful, the address of the PCB list is returned in the field TCADLPCB and TCAFCTR is set to zeros.
If the call is unsuccessful, TCADLPCB contains zeros and TCAFCTR
~ontains a one-byte return code. Before continuing with subsequent DLjI calls, it is the application programmer's responsibility to test these indicators to determine whether scheduling was successful.
The format of the CALL statement to request scheduling is as follows:
For Assembler language:
CALLDLI {ASMTDLIICBLTDLI}, [parmcount, ]function,[psb]) For COBOL:
CALL 'CBLTDLI' USING [parmcount,]function,[psb].
For PL/I:
CALL PLITDLI [parmcount, ]function,[ psb ]) ; where:
parmcount
function
psb
is the name of a binary fullword containing the parameter count (value of one or two). This parameter is optional.
is the name of the field containing the four-character function 'PCBJt' •
is the name of the eight-byte field containing the PSB
generation name which the application program accesses. (This name is one to eight bytes long under CICSjOS/VS, or one to seven bytes long under CICSjDOS/VS, and is left justified and padded on the right with blanks as appropriate.) This parameter is optional. Under CICS/DOS/VS if it is omitted, the PSB name is assumed to be the first PSB name associated with the
application program name in the DL/I application control table generation. Under CICS/OS/VS if it is omitted, the PSB name is assumed to'be the name of the application program associated with the task in the PCT.
Building Segment Search Arguments
Both CICSjOS/VS and CICS/DOS/VS application programmers can use segment search arguments (SSAs) in a DL/I CALL to identify a specific segment, or, if qualified, to identify the range of values within which a segment exists. In addition, the CICS/OS/VS programmer can specify SSAs in a DFHFC TYPE=DL/I macro instruction. If used, SSAs must be built by the application programmer before a DL/I CALL is issued. (For information concerning how to build an SSA, CICSjOS/VS application programmers should refer to the IMSIYS Application Programming Reference Manual;
Chapter 3.3. DL/I Services 131
CICSjDOS/VS users should refer to the DL/I DOS/yS Application ProqramminqReference Manual.)
In a DL/I application program, SSAs are built in fixed storage within the program. In a CICS/VS application program, SSAs must be built in dynamic storage to maintain the quasi-reenterability of the program.
The storage acquired to build the SSAs is addressed as follows:
• For Assembler-language programs, the address should be placed in the register that establishes addressability for the SSA dynamic storage.
• For COBOL programs, the address is moved to the BLL pointer for this storage. The BLL pointer is defined under the COpy DFHBLLDS statement in the Linkage section and must be in the same relative position in the BLL list as the 01 statement for the SSA dynamic storage is among the 01 statements in the Linkage Section.
• - For PL/I, the address is stored in the variable upon which the SSA dynamic storage is based.
After the storage has been acquired and the SSAs built, DL/I CALLs in which the SSAs are used can be issued by the application program. The names of the SSAs to be used, if any, are specified in the parameter list of the CALL. Under CICS/OSjVS, a DFHFC TYPE=DL/I macro instruction can also be used. In a DFHFC TYPE=DL/I macro instruction, the
application programmer can specify the number and names of the SSAs in different ways:
1. SSAS=NO indicates that there are no SSAs in this CALL.
2. SSAS=(ssacount,ssa1,ssa2, ••• ), where ssacount is optional,
represents either the fixed-point number of SSAs in the CALL or the symbolic address of the fullword that contains the number of SSAs.
Specifying a field to contain the number of SSAs provides the application programmer with flexibility in writing one DFHFC
statement to be used in many different CALLs. ssa1, ssa2, ••• , are the symbolic names of the SSAs.
3. SSALIST=YES indicates that the application programmer has built a list of fullwords, optionally containing the number of SSAs ~hich
may be zero) in the first word, and the addresses of the SSAs in the following words, and that he has stored the address of this list at TCA DLSS A.
4. SSALIST=symbolic address indicates that the address of an SSA list built by the application programmer as indicated in item 3 is at the location specified.
In Assembler-language programs, ssacount,ssa1,ssa2, ••• , can be contained in registers if the specifications are enclosed in parentheses"
Acquiring an I/O Work Area
When issuing a request for DL/I services, the address of a work area, either that in which a current segment is contained or that in which DL/I is to place the segment in a retrieval CALL, is required. This area must be specified by the CICSjOSjVS or CICS/DOS/VS programmer who issues a DL/I CALL. It may be provided by the interface, if the
programmer desires, for a retrieval-type DFHFC macro instruction.
138 CICS/VS APRM(!L)
If the CICS/OS/VS application programmer knows the address of the work area to be used in the DFHFC macro instruction, including the case for which storage is acquired for a retrieval-type (GXXX) request, he specifies the name of the pointer to that storage in the WRKAREA=name operand, or he places the address of the storage in TCADLIO before issuing the request and specifies WRKAREA=YES.
If the application programmer wishes to allow the interface to obtain the work area for a retrieval-type request, he does not include the WRKAREA operand in the DFHFC macro request. If the request was serviced successfully, the address of an acquired I/O work area is in TCADLIO.
The address at TCADLIO is the address of the storage accounting area (SAA) preceding the retrieved data. The area becomes the responsibility of the programmer and is not freed until he frees it or until the
transaction terminates. If the application programmer elects to free the work area, he must use a DFHSC TYPE=FREEMAIN macro instruction.
Note: The address of the I/O area is specified as the address of the storage accounting area preceding the data when a DFHFC macro
instruction is used; the address of the first byte of the data area is required when a DL/I CALL is used.
Requesting DL/I Services
The application program request for DL/I services may be either a
CICS/VS DFHFC macro instruction (CICS/OS/VS) or a DL/I call (CICS/OS/VS or CICSjDOS/VS).
DFBFC MACRO INSTRUCTION (CICS/OS/VS)
The format of the DFHFC macro instruction to request that a particular DL/I function be performed is as follows:
r---~---~---,
DFHPC
where:
TYPE= (OL/I [,function])
[,PCB={symbolic addressl (register)}]
[,WRKAREA={symbolic addresslYESI (register)}]
[, SSAS= {NOI ([ ssacount][ ,ssa 1][ ,ssa2, ••• ]) I ([ (register1) ][ , (register2) , ~ •• ])} ]
[,SSALIST={YESINOlsymbolic address I (register)}]
[,NORESP=symbolic address]
[,NOTOPEN=symbolic address]
[,OLINA=symbolic address]
[,FUNCNS=symbolic address]
[,INVREQ=symbolic address]
TYPE=(DL/I [,function])
specifies the two- to four-byte name of the function to be performed. If the function is not specified, it is assumed to be in TCAOLPUN.
Note: OL/I in the TYPE= operand may also be coded as OLI or OL1.
Chapter 3.3. OL/I Services 139
DL/I CALL STATEMENT (CICS/OS/VS OR CICS/DOS/VS)
DL/I data base services are available to CICS/VS application programs through CALL statements. The CALL statement formats for COBOL and PL/I are similar. Por Assembler-language application programs, a CALLDLI macro instruction is used. The formats of the DL/I calls are as follows:
Por Assembler language:
CALLDLI {ASMTDLIICBLTDLI}[ , ([parmcount, ]function,pcb,workarea[,ssa, ••• ])]
Por COBOL:
CALL ICBLTDLII USING [parmcount,]function,pcb,workarea[,ssa, ••• ].
For PL/I:
CALL PLITDLI Warmcount,function,pcb,workarea[,ssa, ••• ]);
where:
parmcount
function
pcb
workarea
is the name of a binary fullword containing the parameter count or argument count of the arguments which follow; this is
optional for Assembler language and COBOL.
is the name of the field containing the four-character DL/I input/output CALL function desired.
is the program communication block (PCB) name (or DSECT name if Assembler) •
is the name of the I/O work area.
ssa1 to ssan
Notes:
are the names of the segment search arguments (SSAs); these are optional.
1. If no parameters are specified in an Assembler-language CALLDLI macro instruction, register 1 is assumed to contain the address of a parameter list.
2. In Assembler language, an alternative format may be used:
CALLDLI (AS!TDLIICBLTDLI},!F=(E,(register) or address) where:
address
is the address of the parameter list, or register that contains the address of the parameter list.
140 CICS/VS APRM(!L)
Releasing a PSB in the CICS/VS Application Program
To reduce pool and intent contention, the CICS/OS/VS application program can release the PSB after a DL/I service has been requested.
It is recommended that conversational programs release the PSB before writing to a terminal so that other transactions can use the PSB while the conversational program is waiting for an operator response.
To ensure data-base integrity, a request to release a PSB other than a read-only PSB implies the end of a logical unit of work for the entire task. This means that a DFHSP TYPE=USER is issued on behalf of a task that is releasing a PSB, unless the PSB is read-only and is resident on the system that issued the call.
DFHFC MACRO INSTRUCTION (CICS/OS/VS ONLY)
To release a PSB for use by other transactions, the CICS/OS/VS
application programmer may issue a macro instruction of the following format:
i
I I I I I I
DFHFC TYPE=(DL/I,{TERMIT})
[,DLINA=symbolic address]
[,TERMNS=symbolic address]
[,INVREQ=symbolic address]
L ______ ~ ______ .~ ________________________________________________________ __
where:
TYPE= (DL/I,TERM)
specifies that the PSB is to be released for use by other transactions, or, if not required, its pool space and
associated DMB pool space may be released for other purposes.
1. DL/1 in the TYPE= operand may also be coded as DL1 or DLI.
2. TERM may be abbreviated as T.
Before issuing any other DL/I CALls or DFHFC macro instructions requesting DL/I access to a data base, the application programmer must again issue a schedule request. All positioning in data bases referred to by the transaction is lost when the PSB is released. Thus, if the program was processing a hierarchy through GNxx requests before
releasing the PSB, it is necessary to explicitly reposition the data bases after issuing another schedule request, to continue the GNxx requests.
DL/I CALL STATEMENT (CICS/DOS/VS OR CICS/OS/VS)
If the CICS/VS application program desires to relinquish control of the PSB, it must issue a terminal call to DL/1. The format of the CALL statement to request termination is as follows:
Chapter 3.3. DL/I Services 141
For Assembler language:
CALLDLI {AS!TDLI ICBLTDLI} , ([parmcount, )function)
For COBOL:
CALL ICBLTDLII USING [parmcount,]function.
For PL/I:
CALL PLITDLI [parmcount, ]function);
where:
parmcount
function
is the name of a binary fullword containing the parameter count value of one.
is the name of the field containing the four-character function
'TER~' or ·T~~~·.
When a termination call is issued for a previously scheduled PSB, the resources acquired for the task are releas8d, and tasks awaiting the resources are given an opportunity to be scheduled.
DL/I Services Response Codes
To test a response code, the application programmer must know the
CICS/VS response codes and their meanings. If the Assembler-language or PL/I programmer elects to use this approach, he can access the response codes for NORESP, INVREQ, and NOTOPEN at TCAFCTR; the response codes for all other conditions can be accessed at TCADLTR. The COBOL programmer can access the response codes for NORESP, INVREQ, and NOTOPEN at
TCAFCRC; the response codes for all other conditions can be accessed at TCADLTR. The possible response codes and the conditions to which they correspond are identified in the right-hand column of Figure 3.3-1.
CICS/VS-DL/I interface requests for which the conditions are applicable are shown at the left.
142 CICS/VS APR~(!L)
I Response Code
DL/I Interface Request Condition I Assembler COBOL PL/I (DL/I, PCB) , (DL/! NORESP X'OO' LOW-VALUES 00000000
[,function]) ,CHECK (Normal (FCNORESP)
Response)
(DL/I[ , function]) , NOTOPEN X'OC' 12-4-8-9 00001100
CHECK (Not open) (FCNOTOPEN)
All INVREQ X'081 12-8-9 00001000
(Invalid (FCINVREQ)
Request)
Codes returned in TCADLTR after NOTOPEN condit10n
r
(DL/![ function]) , Data base X'OO' LOW-VALUES 00000000
CHECK not open;
request issued in
oS/vs
system
Data base X'011 12-1-9 00000001 not open;
request issued in DOS/VS system
Intent XI021 12-2-9 00000010 scheduling
conflict
Codes returned in TCADLTR after INVREQ condition
ALL D/Base not
x·oo·
LOW-VALUES 00000000in FCT, or D/Base not open acc-ording to I FCT, or in-I valid argu-ment passed toDL/I
(DL/! ,PCB) , CHECK PSBNF XIOll 12-.1-9 00000001
(PSB Not (DLPSBNF)
Found)
CHECK TASKNA X' 021 12-2-9 00000010
(Task Not (DLTASKNA)
Authorized)
(DL/I,PCB) , CHECK PSBSCH X103' 12-3-9 00000011
(PSB. Al- (DLPSBSCH)
ready Sche-I
duled I
Figure 3.3-1. (Part 1 of 2) CICS/VS-DL/I Interface Response Codes
Chapter 3.3. DL/I Services 143
DL/I Interface Request
I Test Response to a DL/I Request (TYPE=CHECK)
The format of the DFHFC macro instruction to test the CICSjVS response to a preceding DLjI request is as follows:
~---r---'
DFHFC
where:
TYPE=CHECK
[,NORESP=symbolic address]
[,DLINA=symbolic address]
[ ,PSBSCH=symbolic address]
[,PSBNF=symbolic address]
[,PSBFAIL=symbolic address]
[,FUNCNS=symbolic address]
[,TERMNS=symbolic address]
[,LANGCON=symbolic address]
[,TASKNA=symbolic address]
[,PSBNA=symbolic address]
[ , INVREQ=symbolic address]
[ ,NOTOPEN=symbolic address]
CICS/DOS/VS only CICS/DOSjVS only CICS/DOS/VS only
TYPE=CHECK
indicates that the CICS/VS-DL/1 interface response is to be checked.
The application programmer may use the DFHFC TYPE=CHECK macro instruction following a DL/I CALL statement or a DFHFC
TYPE=(DL/I[,function)) macro instruction. This macro instruction does not check the DL/I return codes in the PCB. If DL/I issues a pseudo-abend during processing of the request, control is not returned to the application program. The transaction is terminated with CICS/VS abend code ADLA. For CICS/DOS/VS, if DL/I issues a pseudo-abend during a call, the transaction is terminated with a Dnnn abend code where nnn is the DL/I pseudo-abend code.
If the application programmer does not provide for the checking of a particular response, and i f the exception condition corresponding to that response occurs, program flow proceeds to the instruction following the DL/I request in the application program.
Chapter 3.3. DL/1 Services 145
DL/I Requests in an Assembler-language Program (CICS/OSNS) USER ftUST PROVIDE ADDRESSABILITY TO PCB'S WHEN USING THEft
CALLDLI CBLTDLI, (PCBFUN) USE PSB FOR THIS PROGRAM CALLDLI CBLTDLI,(PCBFUN,PSBNAftE)GET PCB'S IN SPECIFIED PSB L R1,TCADLPCB GET ADDRESS OF PCB ADDRESS LIST
DFHSC TYPE=GETMAIN, •••
DL/I Requests in a COBOL Program (CICS/OS/VS)
Upon program entry, the COBOL programmer should obtain PCB addresses by issuing a DFHFC TYPE=(DL/I,PCB) request or a DL/I IPCBI call~ After CICS/OS/VS returns control, the programmer moves the contents of
TCADLPCB to the BLL pointer which, is the base for the layout of the PCB pointers in the Linkage section. He then moves the addresses of the PCBs to their BLL pointers to provide the base addresses for the PCBs.
When this is done, the program is in the same state as after an ENTRY 'DLITCBLI USING PCB1,PCB2 statement has been executed in an IftS/VS DLjI application program.
For an explanation of how BLL pointers to 01 statements in the Linkage Section are defined, see the discussion of COBOL application programming in Chapter 2.3~
Examples showing how to write DLjI requests are given below.
some combinations of operands are shown, but other combinations acceptable. Note that, in a DFHFC request, BLL pointers to the
some combinations of operands are shown, but other combinations acceptable. Note that, in a DFHFC request, BLL pointers to the