Retrieve a page

The page retrieval command allows you to retrieve a specified page. If partitions are in use, the page retrieval command re fers to the partition in which it has been entered (see Inquiring on the status of CIND).

Read syntax diagramSkip visual syntax diagramCSPG GETPAGE
 
>>-CSPG--Getpage--+---+--B--+------+--+---------+--------------><
                  '-A-'     +-*ldc-+  '-,hhhhhh-'
                            '-*ALL-'
 
Getpage
This is the user-defined identification code for the retrieval transaction, and is 1-7 characters long. This code is defined by the PGRET system initialization parameter. For convenience, make the code as short as possible; for example, P/.
A
You can ignore this option unless chaining is being used. It is the level, within a chain of logical messages, of the logical message to be retrieved. You must enclose it in parentheses. It can be one of the following:
n
message is at level n
+n
message is n levels forward
-n
message is n levels backward
P
previous level backward
C
current level (the default)
N
next level forward
L
last level.

For more information on levels of messages, see Message chaining with CSPG.

B
Defines the next operation to be performed on the logical message at the current level, or at the level specified by the a option It can be one of the following:
n
page n
+n
page n pages forward
-n
page n pages backward
P
previous page
C
redisplay current page (after clearing the screen)
N
next page
L
last page
A
for an autopaging (that is, hard copy) terminal that is temporarily in paging mode: return the terminal to autopaging mode and output all remaining pages.

This is discussed further under Using Autopage with CSPG.

X
enter data that is not recognized as a paging command.

This is discussed further under Single keystroke retrieval (SKR).

*ldc
Is the LDC for the device to which you want to send the message. (See Page retrieval for logical devices.)
*ALL
A special case of *ldc.
Hhhhhh
Is the 6-digit hexadecimal identifier of an undelivered logical message to be retrieved. You would normally determine this identifier by entering a page query command (see Display information about logical messages).

If you do not specify an identifier, the oldest message is retrieved. After a paging session has started, you can omit hhhhhh because all subsequent pages are from the current message.

In the following examples, P/ is the page retrieval transaction identifier:

P/7
Retrieve page 7 of this message.
P/N
Retrieve next page (following the one being displayed) of this message.
P/(N)9
Retrieve page 9 of the next message (of several that have been chained).

Single keystroke retrieval (SKR)

If you use a 3270 display device under VTAM, you can use PA or PF keys, as defined in the SKRxxxx system initialization parameter, to enter page retrieval commands, and greatly reduce the number of keystrokes necessary in a page retrieval session.

After the session has ended, the PA and PF keys can again be used for initiating transactions in the usual way. The the CICS® System Definition Guide gives further information on this topic.

Page retrieval for logical devices

Your application program can send messages to a communication system such as the IBM 3600. Your application program can also send different pages to each of the logical devices within the system. These pages must be grouped as a single logical message, held in storage.

Each part of a logical message is accompanied by a logical device code (LDC) that identifies its destination. When retrieving the pages for a logical device, you must specify the LDC for that device. However, you do not need to do this if the user-written program in the logical device controller provides a default LDC mnemonic.

If you specify the page number and *ldc, delivery begins with the specified page for that logical device. If the logical device is in AUTOPAGE status, all pages for that logical device, starting with the requested page, are written. If the logical device is in PAGE status, only the specified page is written.

If you omit *ldc, and the application program in the logical device does not provide a default, BMS selects the first page destined for a logical device that is currently in PAGE status. The application program in the logical unit should provide a default LDC, because pages may be delivered to logical devices other than those you originally specified.

In either case, if your request is the first request for a page from a logical message, all pages (within the logical message) destined for logical devices currently in AUTOPAGE status are delivered after the first or specified page is delivered to a device in PAGE status.

The getpageA command supports an *ldc specification for nonrouted messages created for a 3601 logical unit. The various forms of getpageA are interpreted as follows:

Page retrieval and partitions

The page retrieval commands, including any PA and PF keys used in single keystroke retrieval, refer to the partition in which they are entered. For example, P/N means ‘retrieve the next page for this partition’. The partition in which the last paging command is entered is the current partition. A paging command for a partitioned message entered on a nonpartitioned screen (that is, after CLEAR) refers to the current partition.

After a transition from base (unpartitioned) state to partitioned state, or a change of partition set (that is, the initial page display, a page display following CLEAR, or following a change in the level of page chaining), the current page is displayed in each partition. The current page is initially the first page for that partition. It is updated by page retrieval commands.

Display information about logical messages

This command displays the message identifiers and titles of logical messages queued for this terminal.

   getpageQ
Getpage
The user-defined identification code for the retrieval transaction, and is 1-7 characters long. The PGRET system initialization parameter defines this code.
Q
(Query). The identifiers of all logical messages destined for this terminal are displayed. If the message is security protected (that is, if it has been routed to a specific operator ID or operator class), its identifier is displayed only if the operator ID or class for the operator signed on matches that in the message. The identifier consists of a 6-digit hexadecimal number, a 2-character temporary-storage prefix, and optionally, a title. The 6-digit hexadecimal number can be used as the hhhhhh option in the page retrieval command (see Retrieve a page) to retrieve pages for this display.

Related tasks
Using CICS supplied transactions
CSPG--page retrieval
Message chaining with CSPG
CSPG message termination
Copying pages with CSPG
Using Autopage with CSPG
Displaying routed pages with CSPG
[[ Contents Previous Page | Next Page Index ]]