CICS Manual do Usuário - INQUIRE REQID

INQUIRE REQID

Retrieves information about a queued request.

Sintaxe:

INQUIRE REQID
 
>>-INQUIRE REQID(data-value)--+---------------+----------------->
                              '-REQTYPE(cvda)-'
 
>--+-------------------+--+--------------------+---------------->
   '-TERMID(data-area)-'  '-TRANSID(data-area)-'
 
>--+----------------------------------+------------------------->
   +-INTERVAL(data-area)--------------+
   +-TIME(data-area)------------------+
   |       .------------------------. |
   |       V                        | |
   +-AFTER---+-HOURS(data-area)---+-+-+
   |         +-MINUTES(data-area)-+   |
   |         '-SECONDS(data-area)-'   |
   |    .------------------------.    |
   |    V                        |    |
   '-AT---+-HOURS(data-area)---+-+----'
          +-MINUTES(data-area)-+
          '-SECONDS(data-area)-'
 
>--+----------------------------------------------------+------->
   '-SET(ptr-ref)-LENGTH(data-area)-+-----------------+-'
                                    '-FMHSTATUS(cvda)-'
 
>--+---------------------+--+--------------------+-------------->
   '-RTRANSID(data-area)-'  '-RTERMID(data-area)-'
 
>--+------------------+--+-------------------+-----------------><
   '-QUEUE(data-area)-'  '-USERID(data-area)-'

Conditions: END, ILLOGIC, INVREQ, NOTFND

For more information about the use of CICS-value data areas (CVDAs), see Appendix F, CVDAs recognized by the translator.

Description

The INQUIRE REQID command returns information about a queued request.
A queued request results when a DELAY, POST, or START command is issued with a nonzero expiration time.
The queued request lasts until that expiration time arrives.
The expiration time differs for each command, as follows:

Expiration time for a DELAY command is the end of the delay.
Expiration time for a POST command is the time at which posting is to occur.
Expiration time for a START command is the time at which CICS is to create the requested task.

After a request expires, you cannot inquire about it by using the INQUIRE REQID command, even if the action requested is not complete.
For example, a request to START a transaction might be delayed beyond expiration time while it waits for the terminal that it requires.

Requests are identified by the REQID value in the originating command, (orby the value assigned by CICS, if the REQID option was omitted in the command).
The REQID values are normally unique; however, if more than one queued request exists with the same identifier, the INQUIRE REQID command returns information about the request that will expire earliest.

Expiration time can be expressed in either of two ways:

It can be expressed as an interval that gives the length of elapsed time from the time when you issue your INQUIRE command to the time you indicate as the expiration time.
It can be expressed as an absolute value that specifies the amount of time that is to elapse following the midnight that occurs previous to the issue of the INQUIRE command.
If the expiration is set to occur before midnight of the current day, absolute time is the same as time-of-day, using a 24-hour clock.

You can request either form, regardless of how the time was specified in the command that created the request.

Also two formats for expiration time are available, whether it is an absolute value or an interval:

A four-byte packed decimal composite (0hhmmss+), which you obtain by using the TIME or INTERVAL option.
Separate values for hours, minutes and seconds, which you obtain by specifying the HOURS, MINUTES, and SECONDS options with either the AT or AFTER options.

Expiration time and request type (the type of command that produced it) are available for any queued request.
For START requests, additional information is available, including data that is passed from the initiating task to the started task.

START commands have four options for passing data: FROM, QUEUE, RTERMID, and RTRANSID.
The FROM option is primary, and allows you to pass data of variable length. The QUEUE, RTERMID, and RTRANSID options allow you to pass small items of fixed length.
These three options are intended for convenience in conveying resource names to the started transaction, but their use is not restricted to that purpose.
The values for all four data options are kept in temporary storage, and consequently, they are subject to explicit deletion by another task.
If data that you request in an INQUIRE REQID command has been deleted from temporary storage or cannot be read because of an I/O error, CICS raises an INVREQ condition.

Comentários:

You can also browse through all the queued requests by using the browse options (START, NEXT, and END) on INQUIRE REQID commands.

Options

AFTER

Requests that CICS return the expiration time (in the HOURS, MINUTES, and SECONDS options) as the interval between the current time and the expiration time.

Requests that CICS return the expiration time (in the HOURS, MINUTES, and SECONDS options) as an absolute value (following the midnight preceding this inquiry).

FMHSTATUS(cvda)

Returns a CVDA value that indicates whether the data that was passed in the FROM option of the command that created this request contains function management headers (FMH).
The FMHSTATUS option applies only to requests that result from START commands that specify the FROM option.
The CVDA values are:
- FMH
  - The data contains a function management header.
- NOFMH
  - The data does not contain a function management header.
  - This value is always returned.
- NOTAPPLIC
  - The request did not result from a START command, or no FROM data was available.

HOURS(data-area)

Returns a 32-bit binary field that gives the hours portion of the expiration time (see the AT and AFTER options).

INTERVAL(data-area)

Returns the expiration time as an interval from the current time.
The value is a four-byte packed decimal number in the format 0hhmmss+.

LENGTH(data-area)

Returns a 16-bit binary field that gives the length of the data that was passed in the FROM option of the command that created this request.
It applies only to requests that result from START commands that specify the FROM option; for other requests, a null value is returned.

MINUTES(data-area)

Returns a 32-bit binary field that gives the minutes portion of the expiration time (see the AT and AFTER options).

QUEUE(data-area)

Returns the eight-byte field that was passed in the QUEUE option of the START command that created this request.
It applies only to requests that result from START commands that specify the QUEUE option; for other requests, a null value is returned.

REQID(data-value)

Specifies the eight-byte identifier of the request about which you are inquiring.
This is the value that is specified in the REQID option of the command that generated the request, or the value that is assigned by CICS if the REQID option was omitted.

REQTYPE(cvda)

Returns a CVDA value that indicates the type of command that created this request.
The CVDA values are:
- DELAY
  - A DELAY command created this request.
- POST
  - A POST command created this request.
- START
  - A START command created this request.

RTERMID(data-area)

Returns the four-byte field that was passed in the RTERMID option of the START command that created this request.
It applies only to requests that result from START commands that specify the RTERMID option; for other requests, blanks are returned.

RTRANSID(data-area)

Returns the four-byte field that was passed in the RTRANSID option of the START command that created this request.
It applies only to requests that result from START commands that specify the RTRANSID option; for other requests, blanks are returned.

SECONDS(data-area)

Returns a 32-bit binary field that gives the seconds portion of the expiration time (see the AT and AFTER options).

SET(ptr-ref)

Returns the address of the data that was passed in the FROM option of the command that created this request.
It applies only to requests that result from START commands that specify the FROM option; for other requests, the value returned is the CICS null pointer (X'FF000000').

TERMID(data-area)

Returns the four-character terminal identifier that was specified in the TERMID option of the START command that created the request.
It applies only to requests that originate from START commands that specify a terminal; for other requests, blanks are returned.

TIME(data-area)

Returns the expiration time as an absolute value that is measured from the midnight that precedes this INQUIRE command.
The value is a four-byte packed decimal number in the format 0hhmmss+.

TRANSID(data-area)

Returns the four-character transaction identifier that was specified in the TRANSID option of the command that created the request.
It applies only to requests that originate from START commands; for other requests, blanks are returned.

USERID(data-area)

Returns the eight-character identifier of the user that is associated with the task that issued the command that created this request.
The USERID option applies only to requests that result from START commands; for other requests, blanks are returned.

Condições:

END

RESP2 values:
- No more resource definitions of this type exist (RESP2=2).

ILLOGIC

RESP2 values:
- You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress (RESP2=1).

INVREQ

RESP2 values:
- An I/O error occurred while an attempt was made to read data from temporary storage for the SET, QUEUE, RTERMID, or RTRANSID option (RESP2=3).
- Data required for the SET, QUEUE, RTERMID, or RTRANSID option cannot be returned because it has been deleted from temporary storage (RESP2=4).

NOTFND

RESP2 values:
- The REQID cannot be found (RESP2=1).