QWIKREF

Syntax:

QWIKREF(fastpath,stemname[,maxlines][,dropopt][,lrecl])

Arguments:

fastpath

a character string describing the information you want to retrieve. The character string must be in the MVS/Quick-Ref "fast-path" format (see "Specifying the Fastpath String" below).

stemname

the name of the stem array that will contain the lines of retrieved information. The combined lengths of the stemname argument and the largest subscript (including any periods) cannot exceed the REXX maximum length for symbols (250 characters). If stemname is to be a true REXX stem, code a period (.) as the last character. If you do not specify the period, the subscripts will abut the stem name without an intervening period. For example, if you specify a stemname of "ABC.", QWIKREF will create variables of the form "ABC.1", "ABC.2", "ABC.3", etc. If you specify a stemname of "ABC" (no period), QWIKREF will create variables of the form "ABC1", "ABC2", "ABC3", etc.

maxlines

a REXX printable integer, indicating the maximum number of lines of information to retrieve. If the database item specified in fastpath contains more lines than maxlines, the lines beyond maxlines are not retrieved and RC will be set to 4.

dropopt

an option string (only the first character of which is recognized) used to indicate whether the stem given in stemname should be dropped (all existing values are unassigned) prior to retrieving the requested information. The valid values are:

Drop: specifies that stemname is to be dropped prior to retrieval. All stemname variables will be restored to their original un- initialized state.
Nodrop: specifies that stemname is not to be dropped prior to retrieval. Any stemname variables that are not overwritten by the retrieved lines will be preserved. This is the default.

lrecl

a REXX integer indicating the maximul logical record length of the item to be retrieved. This argument is used with MVS/Quick-Ref Version 5 (and later versions) to determine how large a buffer to allocate. It is ignored for earlier versions of MVS/Quick-Ref. The actual LRECL of the data returned may be longer or shorter than the value specified in this argument. The default value is 78.

Module Name:

SWXQR

Service Description:

The QWIKREF function is used to retrieve lines of information from the MVS/Quick-Ref database.

Notes:

You must have licensed MVS/Quick-Ref (Release 3.0 and later) from Chicago-Soft, Ltd. in order to use the QWIKREF function.
Before you invoke the QWIKREF function you must have pre-allocated the MVS/Quick-Ref database to the QWREFDD ddname. If you are going to access a user database, you may also need to allocate the QWREFDDU ddname.
The QWIKREF function uses the MVS/Quick-Ref module QWIKREF1. This module must be accessible to the MVS LINK macro (i.e., it must be in one of: ISPLLIB, a STEPLIB, the link list, or the link pack area). If you attempt to access a user database, you must also make sure that the QWIKREFU module can be loaded via the MVS LOAD macro (the same criteria as for QWIKREF1).
Successful searches return the "top-of-data" and "bottom-of-data" markers (lines) in addition to the lines of text.
As of Release 5.0 of MVS/Quick-Ref, the largest database item contains 2400 lines of information.
For more information refer to the MVS/Quick-Ref User's Guide. See especially the topic of "Direct Program Invocation."

Specifying the Fast-Path String:

The fastpath argument must contain a valid MVS/Quick-Ref "fast-path" string. A fast-path string has the following format:

     topic-indicator'='topic-item

Where topic-indicator is a one character code indicating the type of database item you want to retrieve, and topic-item is the specific database item. Leading, trailing, and embedded blanks are not permitted. A few of the valid topic-indicators are:

M: MVS messages and abend codes
J: JCL syntax
L: MVS utilities syntax
VC: Shadow REXXTOOLS syntax (the topic indicator was '/' in early releases of MVS/Quick-Ref)

A comprehensive discussion of topic indicators can be found in the MVS/Quick-Ref User's Guide.

Returned Information:

The QWIKREF function returns a return code that indicates the success of the operation. If you CALL the QWIKREF function, the returned value is contained in the RESULT special variable. If lines of information are found, they will be returned in stemname-named variables. The zeroth element of the stemname array contains the number of stemname variables created. The RC special variable is set to contain the QWIKREF return code.

The following QWIKREF return code values are possible:

0: The search was successful. The lines of information are contained in the stemname variables. stemname.0 contains the actual number of lines retrieved.
4: The search was at least partially successful. However, the database item you requested contained more lines than could be contained in the internal buffer. The actual number of lines returned is contained in stemname.0. To obtain a larger buffer, specify a larger value for maxlines and/or lrecl.
8: No database item was found that matches the fastpath specification. No lines are returned.
12: The local security exit or PREVENT or ALLOW statement caused the request to be denied.
16: The parameter list for the QWIKREF1 program was incorrect. Repeat the query. If the problem persists, contact Open Software Technologies or your local distributor.
20: The MVS/Quick-Ref database could not be opened. Check to be sure that the QWREFDD name has been allocated.
24: A severe internal error occurred. Repeat the query. If the problem persists, contact Open Software Technologies or your local distributor.
28: The QWIKREFU user database access module could not be loaded. Make sure that this module can be reached via the MVS LOAD macro instruction.
Another possibility is that your license to use MVS/Quick-Ref has expired. Verify the status MVS/Quick-Ref with your systems programmer.

Examples:

Retrieve and display the database entry for message IEF450I:

if qwikref('M=IEF450I','infoline.') = 0 then
  do i = 1 to infoline.0
    say infoline.i
  end