*
*
The application programmer can free a storage area used for temporary data by issuing either the
DFHTS TYPE=RELEASE, *
or
112
CICS/vS Application Pr<Xjrarnmer' s Reference Manual
DFHTS TYPE=PURGE,
macro instruction. The former causes the main or auxiliary storage area used for a single record of temporary data (created by means of a DFHTS TYPE=PUT macro instruction) to be freed. The latter causes all existing entries in a temporary storage queue (created by means of DFHTS TYPE=PUTQ macro instructions) to be freed. There is no way to release selected records froIT a temporary storage message set; in particular, a DFHTS TYPE=RELEASE macro instruction cannot be used to release a record that is part of a message set created by means of DFHTS TYPE=PUTQ.
If temporary data named in a ~FHTS TYPE=RELEASE or DFHTS TYPE=PURGE macro instruction was in main storage, the area that i t occupied is freed and returned to the available dynamic storage area. If the data was in auxiliary storage, the space is made available for reuse.
Temporary data should be released at the earliest possible time to avoid using excessive amounts of storage for this purpose.
The following examples show how to release a single record from temporary storage.
For Assembler language:
MVC TCATSDI,=C'UNIQNME' DFHTS TYPE=RELEASE
For ANS COBOL:
MOVE 'UNIQNME' TO TCATSDI.
DFHTS TYPE=RELEASE For PL/I:
T CATS DI= 'UNIQNME'·;
DFHTS TYPE=RELEASE
TEST RESPONSE TO A REQUEST FOR TEMPORARY STORAGE SERVICES
After issuing a request for fer temporary storage services, the application programmer can check the CICS/VS response to the request to determine subsequent processing that should be carried out. One step in performing this check is to specify the symbolic addresses of user-written exception-handling routines, any of which may be executed as a result of the check. This can be accomplished in any of three ways:
1. Include the symbolic addresses in operands of the DFHTS macro instruction by which the temporary storage service is requested.
2. Include the symbolic addresses in operands of a
DFHTS TYPE=CHECK,
*
*
macro instruction immediately following the DFHTS macro instruction by which the service is requested.
3. Include instructions immediately following the DFHTS macro instruction that examine the response code set automatically by CICS/VS and transfer control to an exception-handling routine accordingly.
The general discussion under "Test Response to a Request for File services" applies to temporary storage services as well. The
Assembler-language or PL/I programmer can access temporary storage
response codes at TCATSTR; the ANS COBOL programmer can access temporary
Figure 6-5. Temporary storage Control Response Codes 114 CICS/VS Application Programmer's Reference Manual
If the application prograrrmer does not check for a particular response to a service request, and if the exception condition
corresponding to that response occurs, prograrr flcw ~roceeds to the next sequential instruction in the application program.
The following examples show how to examine the response code provided by CICS/VS and transfer control to the appropriate user-written
exception-handling routine.
For Assembler language:
GOOD
GOOD.
DFHTS CLI BE DFHPC DS
TYPE=GET,
DATAIJ>:UNIQNME, TSDADDR=YES TCATSTR,X' 00' GOOD
TYPE=ABEND OH
DFHTS TYPE=GET,
DATAID=UNIQNME, TSDADDR=YES
IF TCATSRC=' , THEN GO TO GOOD.
DFHPC TYPE=ABEND
NORMAL RESPONSE
NOTE 12-0-1-8-9 NORESP.
where the value specified within single quotation marks is an
unprintable multipunch code for the required hexadecimal value. For example, a hexadecimal 00 has a multipunch code of 12-0-1-8-9.
* *
* *
The alternative approach to response code checking available to ANS COBOL programmers is generally a coding convenience and provides concise code documentation. When this approach is used, the IF statement above is replaced by a statement of· the form shown below:
IF TSNORESP THEN GO TC GOeD.
For PL/I:
GOOD:
DFHTS TYPE~GET,
*
DATAID=UNIQNME,
*
TSDADDR=YES
IF TCATSTR='OOOOOOOO'B THEN GO TO GOOD; /* NORMAL RESPONSE */
DFHPC TYPE=ABEND
STORAGE SERVICES
storage management controls all dynamic main stcrage for C~CS/VS
and for user-written application programs. Requests to acquire or release main storage are communicated to CICS/VS storage control by means of the storage management macro instruction (DFHSC).
CICS/VS management prograrrs issue requests for main storage to provide input/output areas, program load areas, and user-defined work areas needed to process a transaction. An application program can issue requests for main storage to provide intermediate work areas and any other main storage not automatically provided by CICS/VS but needed to process a transaction. Any main storage acquired by an application program can be initialized tc any bit configuration the user desires.
For example, binary zeros or EBCCIC blanks are a common choice.
All main storage associated with a transaction is controlled and accounted for by CICS/VS. This allows CICS/VS to release all main storage associated with a transaction upon request or when the transaction is normally or abnormally terminated. Main storage is accounted for as follows:
• Task control areaS (TCAs) are accounted fOr through pOinters in the dispatch control areas (DCA). The DCAs are chained from the common system area (CSA).
• Transaction storage is chained off the task control area (TCA).
• Terminal storage is chained off the TCTTE (the TCTTESC field is the origin of the terminal input/output area (TIOA) chain; the TCTTEDA field contains the address of the current TIOA regardless of the position of that TIOA on the chain).
• Program storage is accounted for in the program processing table (PPT) •
• Suspended tasks are accounted for by the suspending CICS/VS management program (task control, storage control, Or temporary storage control).
If there is insufficient rrain storage to satisfy a storage
acquisition request, TCASCSA is filled with binary zeros. All activity within the task is suspended until sufficient dynamic storage becomes
available and its address is placed in TCASCSA, unless the application programmer has specified in his request that control is to be returned to the application program. No storage will cause a short-on-storage condition. The initiation of new tasks is restricted by CICS/VS until the short-on-storage condition is alleviated. Normally, this occurs as a result of some other task releasing storage currently reserved for it. (See "Purge a Task on System OVerload (PURGE/NOPURGE) II for corrective action that can be taken if the short-on-storage condition contin ue s. )
OBTAIN AND INITIALIZE MAIN STORAGE (GETMAIN)
Requests for wain storage are made by issuing the DFHSC TYPE=GETMAIN,
macro instruction. This instruction is used by the application programmer to obtain main storage of a specified size and class and, 116 CICS/vS Application Programmer's Reference Manual
*
optionally, to initialize that storage to a bit configuration the application programmer desires. The address of the storage area obtained upon execution of this instruction is placed in TCASCSA by CICS/VS; the obtained storage is doubleword-aligned.
When using the DFHSC TYPE=GETMAIN macro instruction, the application programmer should: allowed for a DFHSC TYPE=GETMAIN macro instruction.
• Specify a symbolic base address for the storage area. INI'I'IALIZE WITH BINARY ZEROS SIZE OF STORAGE REQUESTED
INI~IALIZE WITH EINARY ZEROS SIZE OF STORAGE REQUESTED OFI'AIN NEW STORAGE AREA
INI~IALIZE WITH BINARY ZEROS RETURN CONTROL IF NO STORAGE CLASS OF STORAGE REQUESTED WAS STORAGE AVAI~ABLE?
BRANCH IF NOT
LOA!: REGISTER IF STORAGE FOUND
NOTE INITIALIZE WITH BLANKS NOTE SIZE OF STORAGE REQUESTED.
-IF TCASCSA EQUAL 0 GO TO NOSTRG.
MOVE TCASCSA TO TIOABAR.
!2!:
~:TCASCIB=O;
TCASCNB= 1024;
DFHSC ~YPE=GETMAIN,
INITIMG=YES, COND=(NO,NOSTRG), CLASS=TERMINAL IF TCASCSA = 0 THEN GO TO TIOABAR=TCASCSA;
RELEASE MAIN STORAGE (FREEMAIN)
/*INITIALIZE WITH BINARY ZEROS*/
l'*SIZE OF STORAGE REQUESTED*/
OBTAIN NEW STORAGE AREA INITIALIZE WITH BINARY ZEROS RETURN CONTROL IF NO STORAGE CLASS OF STORAGE REQUESTED NOSTRG;
/*LOAr REGISTER IF STORAGE FOUND*/
Previously acquired main storage is released by issuing the DFHSC TYPE=FREEMAIN,
macro instruction. If the task itself does not release acquired storage, the storage is released by CICS/VS upon termination of the task.
* *
*
If using the DFHSC TYPE=FREEMAIN macro instruction to release a single storage area, the application programmer must place the address of that area in TCASCSA frior to execution of the DFHSC TYPE=FREEMAIN macro instruction. If all terminal storage acquired by means of DFHSC
TYPE=GETr~IN,CLASS=TERMINAL macro instructions in the application program or by CICS/VS on behalf of the task is to be released, the RELEASE=ALL operand can be coded in the DFHSC TYPE=FREEMAIN macro instruction to achieve that result; in this case, i t is not necessary to place an address in TCASCSA.
*
The following example shows hew to release all main storage currently allocated to a specific terminal:
DFHSC TYPE=FREEMAIN,
RELEASE=ALL RELEASE ALL TERMINAL STORAGE The following examples shew how to release a single main storage area, placing the address of the area to be released in TCASCSA before issuing the release request.
For Assembler language:
ST TIOABAR,TCASCSA PLACE STORAGE AREA ADDRESS IN TCA
DFHSC TYPE=FREEMAIN RELEASE STORAGE AREA
MOVE TIOAEAR TO TCASCSA. NOTE PLACE STRG AREA ADDR IN TCA.
*
' - - - -
- - - -
- - -- - - - - - - ---- - - - - -
-_.-118 CICS/vS Application Programmer's Reference Manual
- - - - - - - - - - --- - - - -
- - - ,DFHSC TYPE=FREEMAIN RELEASE STORAGE AREA For PL/I:
TCASCSA=TIOABAR; /*PLACE STORAGE AREA ADDRESS IN TCA*/
DFHSC TYPE=FREEMAIN RELE..~SE STORAGE AREA PROGRAM SERVICES
All program communication within CICS/VS is accom~lished by program management. The program management macro instruction (DFHPC) is used to request any of the following services:
• Link one user-written ap~lication program to another, anticipating subsequent return to the requesting program.
• Transfer control from one user-written application program to another, anticipating no return to the requesting program.
• Load a designated ap~lication program, table, or map (generally, for use with basic mapping support) into main storage and return control to the requesting prcgram.
• Return central from one user-written application program to another or to CICS/VS.
• Delete a previously loaded application program from main storage.
• Abnormally terminate a transaction and its related task.
• Activate, cancel, or reactivate an exit that ~ermits user-written abnormal termination processing.
• Convert a symbolic label in an ANS COBOL application progrfu~ into an address (returned in TCAPCLA) •
Application programs running under CICS/VS are executed at various logical levels. For exa~ple, where one user-written application program is linked to another, the linked-to program is considered to reside at the next lower logical level. Where control is simply transferred from one application program to another, the two programs are considered to reside at the same logical level. A program control DFHPC TYPE=LINK macro instruction is used for the former; a DFHPC TYPE=XCTL macro
instruction (where XCTL means transfer control) is used for the latter.
Figure 6-6 illustrates this difference between program linkage and transfer of program control. Each of the prograrrs shown in this figure may have been written in any of the CICS/VS-supported languages
(Assembler language, ANS COBOL, or PL/I). Use of LINK, XCTL, RETURN, and ABEND is explained in greater detail below.
Transactions can share the use of common work areas. However, each transaction requires the use of a unique intermediate storage area, such as the transaction work area (TwA), to retain information needed upon subsequent return to that transaction. The application programmer must provide addressability to that intermediate storage area by
symbolically defining i t in his ~rogram.
Parameters can be passed from one program to ancther through user-defined storage areas, for example, the transaction work area
(TWA), the terminal input/output area (TIOAl, the terminal control Table terminal entry (TCTTE), or the file work area (FWA).
PROGRAM
CICS/VS automatically saves program control infcrmation and
general-purpose registers, when applicable, in the task control area (TCA). CICS/VS automatically restores general-purFose registers, as necessary, to return control to a program. The name of any program referenced in a request for program services must have been placed in the processing program table (PP~) prior to execution of CICS/VS.
t
CICS/VS Program Control
I t
Application
LINK
~ Program A
-"... ~ RETURN XCTL
"
•
Application Application
LINK
Program
--..
ProgramB C
r-- ~
/ " ... RETURN XCTL
"
Application Program 0
I--Figure 6-6. Communication and Logical RelationshiFs among Application Programs
PASS PROGRAM CONTROL ANTICIPATING RETURN (LINK)
•
Application Program E
~
RETURN
Program control is passed from a user-written application program at one logical level to a user-written application program at the next lower logical level in response to the
120 CICS/vS Application Programmer's Reference Manual
DFHPC TYPE=LINK,
macro instruction. When the DFHPC TYPE=RETURN macro instruction is executed in the linked-to program, control is returned to the program initiating the linkage at the next sequential (executable) instruction.
The application programmer must specify the name (identification) of the program to which control is passed in the DFHPC TYPE=LINK macro instruction or in a single instruction that places the program name in TCAPCPI prior to issuing the DFHPC TYPE=LIN~ macro instruction.
The following example sho~s hcw to request a link to a particular application program:
DFHPC TYPE=LINK, PROGRAM=PROG1
The following examples show how to link to an application program specified dynamically by an instruction executed ~rior to DFHPC TYPE=LINK.
For Assembler language:
MVC TCAPCPI,=CL8'FROG1' PLACE LINKED-TO PROGRAM NAME IN TCA
· · ·
DFHPC TYPE=LI.NK LINK TO PROGRAM AT NEXT LOWER LEVEL For ANS COBOL:
MOVE 'PROG1 ' TO TCAPCPI. NOTE LINKED-TO PROGRAM NAME TO TCA.
· ·
·
DFHPC TYPE=LINK LINK TO PROGRAM AT NEXT LOWER LEVEL For ~:
*
TCAPCPI='PROG1'; /*PLACE LINKED-TO PRGM NAME IN TCA*/
· ·
DFHPC TYPE=LINK
·
LI NK TO PROGRAM AT NEXT LOWER LEVELTRANSFER PROGRAM CONTROL (XCTL)
Program control is transferred from one user-written application program to another at the same logical level in response to the
DFHPC TYPE= XCTL ,
macro instruction. The prcgram from which control is transferred is released. Any return from the transferred-to program is to a program from which there was an exit at the next higher logical level. If there is no user-written application program at the next higher logical level, centrol is returned to CICS/VS.
*
*
The application programmer must specify the name (identification) of the program to which control is transferred in the DFHPC TYPE=XCTL macro instruction or in a single instruction that ~laces the program name in TCAPCPI prior to issuing the DFHPC TYPE=XC~L macro instruction.
The following example shows how to request a transfer of control to a particular application program:
DFHPC TYPE=XCTL,
PROGRAM=PROG2
*
The following examples show how to transfer control to an application program specified dynamically by an instruction executed prior to DFHPC TYPE=XCTL.
!.2!:
Assembler language:MVC TCAPCPI,=CL8'PRGG2' PLACE TRANSFERRED-TO PRGM NAME IN TCA
· · ·
DFHPC TYPE=XCTL TRANSFER PROGRAM CONTROL For ANS~:
MOVE 'PROG2' TO TCAPCPI. NOTE TRANSFERRED-TO PRGM NAME TO TCA.
· ·
DFHPC TYPE=XCTL
·
TRANSFER PROGRAM CONTROLFor PL/I:
TCAPCPI= , PROG2' ; /*PLACE PROGRAM NAME IN TCA*/
· ·
DFHPC TYPE=XCTL
·
TRANSFER PROGRAM CONTROLLOAD A PROGRAM (LOAD)
Programs, tables, or maps are fetched from the library where they reside and loaded into main storage in response to the
DFHPC TYPE=LOAD,
macro instruction, which identifies the program to be loaded. This facility is used to (1) load a program that will be used repeatedly, thereby reducing system overhead through a one-time load, (2) load a table to which control is not to be passed, or (3) load a map to be used in a mapping operation (see Chapter 10). CICS/VS returns the address of the leaded program in TCAPCLA.
*
The loaded program remains in main storage until the DFHPC
TYPE=DELETE macro instruction is issued or until the task that issued the DFHPC TYPE=LOAD is terminated, either normally or abnormally (unless LOADLST=NO was specified). If the LOADLST=NO operand is used, the
loaded program remains resident until i t is deleted by the user.
122 CICS/VS Application Programmer's Reference Manual
The application programmer muet provide the name (identification) of the program to be loaded in the DFHPC TYPE=LOAC macro instruction or in a single instruction that ~laces the prograrr name in TCAPCPI prior to issuing the DFHPC TYPE=LOAD macro instruction.
The following example sho~s hew to load a particular user-written application program:
DFHPC TYPE=LOAD, PROGRAM=PROG3
The following examples show how to load an application program specified dynamically by an instruction executed prior to DFHPC TYPE=LOAD.
For Assembler language:
MVC TCAPCPI,=CLS'PROG3' PLACE PROGRAM NAME IN TCA
· · ·
DFHPC TYPE=LOAD LOAC THE SPECIFIED PROGRAM For ANS COBOL:
MOVE 'PROG3' TO TCAPCPI. NOTE PLACE PRGM NAME IN TCA.
· ·
DFHPC TYPE=LOAD
·
LOAD THE SPECIFIED PROGRAMFor PL/I:
TCAPCPI=' PROG3' ; /*PLACE PROGRAM NAME IN TCA*/
· ·
DFHPC TYPE=LOAD
·
LOAD THE SPECIFIED PROGRAM RETURN PROGRAM CONTROL (RETURN)*
Program control is returned from an applicaticn program to a program at the next higher lcgical level in response to the
DFHPC TYPE=RETURN,
macro instruction. When this macro instruction is executed in a lower level (linked-to) program, i t restores the registers of the higher level (linked-from) program to their contents at the time the 'DFHFC TYPE=LINK was issued and releases save areas for the lower-level program. In general, the program to which control is returned must have relinquished control by execution of a DFHPC TYPE=LINK macro instruction and must reside one logical level higher than the program returning control. Upon normal termination of transaction processing, control is returned to CICS/VS.
If no default transaction code has been assembled into the terminal control table terminal entry (TCTTE) for a particular terminal, the application programmer can specify the transaction identification for
*
the next program to be associated with that terminal in either- of two ways: (1) by including the desired transaction identification in the DFHPC TYPE=RETURN macro instruction, or (2) by coding a single
instruction that places the desired transaction identification in TCANXTID prior to issuing the DFHPC ~YPE=RETURN macro instruction. By doing so, the programmer ensures that subsequent unsolicited input can be entered from the terminal without the specification of a transaction identification. A flexible means of starting the next transaction
(task) is provided. Any higher-level program specification of
transaction identification overrides a specification by a lower-level
~rogram.
DELETE A LOADED PROGRAM (DELETE)
A program previously leaded through use of the DFHPC TYPE=LOAD macro instruction with or without the LOADLST=NO operand is deleted (released) by the
DFHPC TYPE=DELETE,
macro instruction. If the DFHPC TYPE=LOAD macro instruction contained LOADLST=NO, the loaded program is deleted only in response to a DFHPC TYPE=DELETE macro instruction. If LOADLST=NO was not specified, the
loaded program can be deleted by a DFHPC TYPE:DEIETE request, or i t
*
will be automatically deleted when the task that issued the load request is terminated.
The application programmer must specify the name (identification) of the program to be deleted in the DFHPC TYPE=DELETE macro instruction or in an instruction that ~laces the program name in TCAPCPI prior to issuing the DFHPC TYPE=DELETE macro instruction.
The following example shows how to delete a user-written application program loaded in response to a DFHPC TYPE=LOAD macro instruction.
The following example shows how to delete a user-written application program loaded in response to a DFHPC TYPE=LOAD macro instruction.