The only disposition option we have described up to this point is TERMINAL, which sends the output to the principal facility of your task. TERMINAL is the default value that you get if you do not specify another disposition. There are, however, two other possibilities:
When you use PAGING, the output still goes to your principal facility, though indirectly, as just described. Full BMS also provides a feature, routing, that lets you send your message to another terminal, or several, in place of or in addition to your own. We tell you about routing in Message routing, after we cover the prerequisites.
When you specify a disposition of SET for a BMS message, BMS formats your output and returns it in the form of a device-dependent data stream. No terminal I/O occurs, although the returned data stream usually is sent to a terminal subsequently.
There are several reasons for asking BMS to format a data stream without sending it. You might want to do any of the following:
BMS returns formatted output by setting the pointer variable named in the SET option to the address of a page list. This list consists of one or more 4-byte entries in the following format, each corresponding to one page of output.
Bytes | Contents |
---|---|
0 | Terminal type (see Table 39) |
1-3 | Address of TIOA containing the formatted page of output |
An entry containing -1 (X'FF') in the terminal type signals the end of the page list. Notice that the addresses in this list are only 24 bits long. If your program uses 31-bit addressing, you must expand a 24-bit address to a full word by preceding it with binary zeros before using it as an address.
Each TIOA (terminal input-output area) is in the standard format for these areas:
Field name | Position | Length | Contents |
---|---|---|---|
TIOASAA | 0 | 8 | CICS storage accounting information (8 bytes) |
TIOATDL | 8 | 2 | Length of field TIOADBA in halfword binary format |
(unnamed) | 10 | 2 | Reserved field |
TIOADBA | 12 | TIOATDL | Formatted output page |
(unnamed) | TIOATDL + 12 | 4 | Page control area, required for the SEND TEXT MAPPED command (if used) |
The reason that BMS uses a list to return pages is that some BMS commands produce multiple pages. SEND MAP does not, but SEND TEXT can. Furthermore, if you have established a routing environment, BMS builds a separate logical message for each of the terminal types among your destinations, and you may get pages for several different terminal types from a single BMS command. The terminal type tells you to which message a page belongs. (Pages for a given type are always presented in order.) If you are not routing, the terminal type is always that of your principal facility.
If you are not using the ACCUM option, pages are available on return from the BMS command that creates them. With ACCUM, however, BMS waits until the available space on the page is used. BMS turns on the RETPAGE condition to signal your program that pages are ready. You can detect RETPAGE with a HANDLE CONDITION command or by testing the response from the BMS command (in EIBRESP or the value returned in the RESP option).
You must capture the information in the page list whenever BMS returns one, because BMS reuses the list. You need save only the addresses of the pages, not the contents. BMS does not reuse the pages themselves, and, in fact, moves the storage for them from its control to that of your task. This allows you to free the storage for a page when you are through with it. If you do this, the DATA or DATAPOINTER option in your FREEMAIN command should point to the TIOATDL field, not to TIOASAA.
[[ Contents Previous Page | Next Page Index ]]