Dynamic allocation sample program (IBM 3270 only)
Any data set defined to file control can be allocated to CICS® dynamically when the file is opened, rather than at CICS job initiation time. This allocation takes place automatically if job control statements for the data set are not included in the CICS job stream, and if both the data set name and the disposition have been specified in the resource definition when the data set is opened. The dynamic allocation sample program provides an alternative way to perform dynamic allocation. When used with a terminal of the IBM® 3270 Information Display System, it gives the user access to the functions of DYNALLOC (SVC 99) in z/OS®. This can be used, in conjunction with main terminal functions and suitable operating procedures, to allocate and deallocate any file that CICS can dynamically open and close.
Design overview
The program runs as a CICS transaction, using CICS functions at the command level wherever possible. It does not modify any CICS control blocks. Only the DYNALLOC function is available through the program; any manipulation of the environment before or after the DYNALLOC request must be done by other means.
CICS supplies sample resource definitions for the program load module, DFH99, and the transaction, ADYN, that invokes it. These definitions are in the group DFH$UTIL. Note that DFH99 must be defined with EXECKEY(CICS).
The flow in a normal invocation is as follows. The main program, DFH99M, receives control from CICS, and carries out initialization. This includes determining the screen size and allocating input and output buffer sections, and issuing initial messages. It then invokes DFH99GI to get the input command from the terminal. Upon return, if the command was null, the main program terminates, issuing a final message.
The command obtained has its start and end addresses stored in the global communication area, COMM. The main program allocates storage for tokenized text, and calls DFH99TK to tokenize the command. If errors were detected at this stage, further analysis of the command is bypassed.
Following successful tokenizing, the main program calls DFH99FP to analyze the verb keyword. DFH99FP calls DFH99LK to look up the verb keyword in the table, DFH99T. DFH99LK calls DFH99MT if an abbreviation is possible. Upon finding the matching verb, DFH99FP puts the address of the operand section of the table into COMM, and puts the function code into the DYNALLOC request block.
- For character and numeric strings, DFH99CC is called. It validates the string, and puts its length and value into the text unit.
- For binary variables, DFH99BC is called. It validates the value, converts it to binary of the required length, and puts its length and value into the text unit.
- For keyword values, DFH99KC is called. It looks up the value in the description part of the keyword table using DFH99LK, and puts the coded equivalent value and its length into the text unit.
When a keyword specifying a returned value is encountered, DFH99KO makes an entry on the returned value chain, which is anchored in COMM. This addresses the keyword entry in DFH99T, the text unit where the value is returned, and the next entry. In this case the conversion routine is still called, but it only reserves storage in the text unit, setting the length to the maximum and the value to zeros.
When all the operand keywords have been processed, DFH99KO returns to the main program, which calls DFH99DY to issue the DYNALLOC request.
DFH99DY sets up the remaining parts of the parameter list, and if no errors too severe have been detected, a subtask is attached to issue the DYNALLOC SVC. A WAIT EVENT is then issued against the subtask termination ECB. When the subtask ends, and CICS dispatches the program again, the DYNALLOC return code is captured from the subtask ECB, with the error and reason codes from the DYNALLOC request block, and a message is issued to give these values to the terminal.
DFH99DY then returns to the main program, which calls DFH99RP to process returned values. DFH99RP scans the returned value chain, and for each element issues a message containing the keyword and the value found in the text unit. If a returned value corresponds to a keyword value, DFH99KR is called to look up the value in the description, and issue the message.
Processing of the command is now complete, and the main program is reinitialized for the next one, and loops back to the point where it calls DFH99GI.
Messages are issued at many places, using macros. The macro expansion ends with a call to DFH99MP, which ensures that a new line is started for each new message, and calls DFH99ML, the message editor. Input to the message editor is a list of tokens, and each one is picked up in turn and converted to displayable text. For each piece of text, DFH99TX is called, which inserts the text into the output buffer, starting a new line if necessary. This ensures that a word is never split over two lines.
When the command has been processed, the main program calls DFH99MP with no parameters, which causes it to send the output buffer to the terminal, and initialize it to empty.
Control blocks
The sample program does not have any control blocks.
Modules
| Module | Function |
|---|---|
| DFH99BC | Convert to binary target |
| DFH99CC | Character and number string conversion |
| DFH99DY | Issue SVC 99 and analyze result |
| DFH99FP | Process function keyword |
| DFH99GI | Format display and get input |
| DFH99KC | Keyword value conversion |
| DFH99KH | List keywords for help |
| DFH99KO | Process operator keywords |
| DFH99KR | Convert returned value to keyword |
| DFH99LK | Search key set for given token |
| DFH99ML | Build message text from token list |
| DFH99MM | Main control program (entry point DFH99M) |
| DFH99MP | Message filing routine |
| DFH99MT | Match abbreviation with keyword |
| DFH99RP | Process returned values |
| DFH99T | Table of keywords |
| DFH99TK | Tokenize input command |
| DFH99TX | Text display routine |
| DFH99VH | List description for help |
Exits
No global user exit points are provided for this function.
Trace
This sample program makes no entries in the trace other than the normal entries for a CICS user transaction.
External interfaces
SVC 99—MVS DYNALLOC SVC.