Run Query (RUNQRY)
| Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
The Run Query (RUNQRY) command runs an existing query or a default query if only a file name is specified for this command. The query gets information from the system database and produces a report of that information. The report is created in either detailed or summary form. The definition of the query can be printed when output to a printer or database file is specified. The output is shown, printed, or stored in a database file. The command is used in three ways: to run an existing query (one that has already been created), to run an existing query with some of its values changed by values specified on this command, or to run a default query based only on the defaults and values specified in this command.
- To run an existing query without changing the file or files to query, use the QRY parameter (without the QRYFILE parameter) to specify the name of the query.
- To run a changed version of an existing query, use the QRY parameter and the appropriate parameters to change the definition as desired. The parameter values specified on this command override the corresponding values in the existing query definition, but only when the command is processing. For example, use the QRYFILE parameter to indicate a different file or list of files to use in the query.
- To query a file without a previously defined query definition, use the QRYFILE parameter to specify which file to query. Only one file name can be specified for a default query.
If you specify both the QRY and QRYFILE parameters, the files specified in the QRYFILE parameter override the file names specified in the query. Therefore, if multiple files (and members) are defined in the query definition and you want to change one or two of them, specify *SAME for the file selections that do not change, and specify the values for the files to override.
Notes:
- When a changed version of an existing query is run, the changes specified on the RUNQRY command do not change any of the values in the query definition itself; they affect only the results of the report being run.
- If an existing query (identified on the QRY parameter) is used, *RUNOPT is the default value for any unspecified parameters; that is , the same value specified (or assumed) in the definition of the query is used as the default. If this is a default query, the default value is not *RUNOPT, but is the next predefined value listed in the syntax diagram.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| QRY | Query | Single values: *NONE Other values: Qualified object name |
Optional, Positional 1 |
| Qualifier 1: Query | Name | ||
| Qualifier 2: Library | Name, *LIBL, *CURLIB | ||
| QRYFILE | Query file | Values (up to 32 repetitions): Element list | Optional, Positional 2 |
| Element 1: File | Qualified object name | ||
| Qualifier 1: File | Name, *SAME | ||
| Qualifier 2: Library | Name, *RUNOPT, *LIBL, *CURLIB | ||
| Element 2: Member | Name, *RUNOPT, *FIRST, *LAST, *ALL | ||
| OUTTYPE | Report output type | *RUNOPT, *DISPLAY, *PRINTER, *OUTFILE | Optional, Positional 3 |
| OUTFORM | Output form | *RUNOPT, *DETAIL, *SUMMARY | Optional |
| RCDSLT | Record selection | *NO, *YES | Optional |
| PRTDFN | Print query definition | *RUNOPT, *NO, *YES | Optional |
| PRTDEV | Print device | Name, *RUNOPT, *PRINT | Optional |
| FORMSIZE | Form size | Element list | Optional |
| Element 1: Form length | 1-255, *RUNOPT | ||
| Element 2: Form width | 1-378, *RUNOPT | ||
| FORMTYPE | Form type | Character value, *RUNOPT, *STD | Optional |
| COPIES | Copies | 1-255, *RUNOPT | Optional |
| LINESPACE | Line spacing | *RUNOPT, 1, 2, 3 | Optional |
| OUTFILE | Output file | Element list | Optional |
| Element 1: File | Qualified object name | ||
| Qualifier 1: File | Name, *RUNOPT | ||
| Qualifier 2: Library | Name, *RUNOPT, *CURLIB | ||
| Element 2: Member | Name, *RUNOPT, *FIRST, *LAST, *ALL | ||
| Element 3: Option | *RUNOPT, *NEWFILE, *RPLFILE, *NEWMBR, *RPLMBR, *ADDMBR | ||
| AUT | Authority | Name, *RUNOPT, *LIBCRTAUT, *USE, *CHANGE, *ALL, *EXCLUDE | Optional |
| Top |
Query (QRY Parameter)
Specifies the name of an existing query to be run. If QRY is not specified, QRYFILE must be specified.
The possible values are:
- *NONE
- No existing query definition is used. Instead, a default query (or quick query) is used to get information from the file specified on the QRYFILE parameter.
- query-name
- Specify the name of the query to run.
If no value is specified, the file or files that were specified when the query was defined are the files to be queried.
The name of the query can be qualified by one of the following library values:
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- *CURLIB
- The current library for the job is used to locate the specified query definition. If no library is specified as the current library for the job, the QGPL library is used.
- library-name
- Specify the library where the query is located.
| Top |
Query file (QRYFILE Parameter)
Specifies the database file or files to be queried for information. If the QRY parameter is specified, as many as 32 files can be specified on this parameter by using the file names and/or using the default value *SAME for one or more of the files. If the QRY parameter is not specified, only one file name can be specified on this parameter. If QRYFILE is not specified, QRY must be specified.
If no value is specified, the file or files that were specified when the query was defined are the files used to run the query.
You can enter multiple values for this parameter.
There are two parts to this parameter.
Element 1: Database File Name
The possible values are:
- data-base-file-name
- Specify the names of one or more database files that contain the data from which the system gets information to produce the output. Up to 32 files can be specified.
- *SAME
- The list of files remains the same as defined in the query definition.
The name of a database file can be qualified by one of the following library values:
- *SAME
- The value of the library, file, and member do not change for the file in this position within the list. The values are the same as defined in the query. Any values specified for the library, file, and member are ignored.
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- *CURLIB
- The current library for the job is used to locate the database file. If no library is specified as the current library for the job, QGPL is used.
- *RUNOPT
- The library specified for the file selection is used.
- library-name
- Specify the library where the database file is located.
Element 2: Database File Member
The possible values for member name are:
- member-name
- Specify the name of the file member to be queried.
- *RUNOPT
- The member specified for this file selection is used.
- *FIRST
- The first member in the file is the member to be queried.
- *LAST
- The last member in the file is the member to be queried.
- *ALL
- The input file is a partitioned table, where all of the members in the file are to be queried.
| Top |
Report output type (OUTTYPE Parameter)
Specifies where the report or output produced by the query is sent. If a value is not specified in the query, and is not entered on the command, or if a query name is not specified, *DISPLAY is assumed.
The possible values are:
- *RUNOPT
- If a query definition is being used, the type of output specified in the query definition is the type of output produced when this query is run.
- *DISPLAY
- The output produced by the query is sent to the display station that runs the command. If run in batch, the output is sent to the printer instead of the display.
- *PRINTER
- The output produced by the query is printed.
- *OUTFILE
- The output is directed to the database file specified on the OUTFILE parameter.
| Top |
Output form (OUTFORM Parameter)
Specifies the form of output produced by the query. If no value was specified in the query and no value was entered on the command, or if a query name is not specified, *DETAIL is assumed.
The possible values are:
- *RUNOPT
- If a query definition is used, the output form specified in the query definition is used when this query is run.
- *DETAIL
- The output form produced by the query is a report containing detail records and summary records if any exist.
- *SUMMARY
- The output form produced by the query is a report containing summary records only.
| Top |
Record selection (RCDSLT Parameter)
Specifies whether or not the query is run with a run time selection test.
Note: The Query for i5/OS licensed program must be installed and the query must be run interactively to specify *YES.
The possible values are:
- *NO
- The query is run without showing the record selection display in Query.
- *YES
- Record selection definition is allowed for this run only. A display is shown on which you can change the record selection tests defined in the query or specify record selection tests if a query name was not specified.
Note: For output to display, query can be run repeatedly.
| Top |
Print query definition (PRTDFN Parameter)
Specifies whether or not the query definition is printed with the report when the query is run. The definition can be printed when the output of the query is printed or is stored in a database file, as determined by the OUTTYPE parameter. If a value is not specified in the query, or in this parameter, or if a query name is not specified, the value *NO is assumed.
The possible values are:
- *RUNOPT
- If a query definition is being used when the query is run, the print option specified in the query definition is used.
- *NO
- The query definition is not printed when the query is run.
- *YES
- The query definition is printed in the report. *YES cannot be specified if OUTTYPE(*DISPLAY) is specified or assumed.
| Top |
Print device (PRTDEV Parameter)
Specifies the printer device on which the report is printed. If no value is specified, the printer that was specified when the query was defined is assumed. If no printer is specified in the query or in this parameter, or if a query name is not specified, the value *PRINT is assumed.
Note: If an override is in effect for the printer file QPQUPRFIL, this parameter uses the value specified by the override.
The possible values are:
- *RUNOPT
- If a query definition is being used, the printer specified in the query definition is used to print the output when this query is run.
- The default printer, as defined by QPQUPRFIL, is used to print the output when this query is run.
- printer-device-name
- Specify the name of the printer that is used to print the output when this query is run.
| Top |
Form size (FORMSIZE Parameter)
Specifies the length and the width of the forms on which the report is printed. If a form width greater than 132 is specified, Query will open the file with CPI(15) and FONT(*CPI). If no value is specified in the query or in this parameter, or if a query name is not specified, 132 is the assumed form width, and the value from the file QPQUPRFIL is the assumed form length.
Note: If an override is in effect for the printer file QPQUPRFIL, this parameter uses the value specified by the override.
There are two parts to this parameter.
Element 1: Form Length
- *RUNOPT
- If a query definition is being used when the query is run, the form size specified in the query definition is used. If the form size specified in the query definition is blank, the value from QPQUPRFIL is assumed.
- form-length
- Specify the form length used when this query is run. Valid values range from 1 through 255.
Element 2: Form Width
- *RUNOPT
- If a query definition is being used when the query is run, the form size specified in the query definition is used. If the form size specified in the query definition is blank, the value from QPQUPRFIL is assumed.
- form-width
- Specify the form width used when this query is run. Valid values range from 1 through 378.
| Top |
Form type (FORMTYPE Parameter)
Specifies the type of form on which the output is printed. The identifiers used to indicate the type of forms are user-defined and can be a maximum of 10 characters in length.
Note: If a value is not specified in the query or on this parameter, or if a query name is not specified, the value in QPQUPRFIL is assumed. If an override is in effect for the printer file QPQUPRFIL, this parameter uses the value specified by the override.
The possible values are:
- *RUNOPT
- If a query definition is being used, the form type specified in the query definition is used when this query is run.
- form-type
- Specify the form type that is used when this query is run.
| Top |
Copies (COPIES Parameter)
Specifies the number of copies being printed.
Note: If a value is not specified in the query or on this parameter, or if a query name is not specified, 1 is the assumed number of copies. If an override is in effect for the printer file QPQUPRFIL, this parameter uses the value specified by the override.
The possible values are:
- *RUNOPT
- If a query definition is being used, the number of copies specified in the query definition is used when this query is run. If the number of copies specified in the query definition is blank, the number of copies from QPQUPRFIL is assumed.
- number-of-copies
- Specify the number of copies to print when this query is run. Specify a number ranging from 1 through 255.
| Top |
Line spacing (LINESPACE Parameter)
Specifies the number of blank lines to leave between lines in the report. The numbers range from 1 through 3. If a value was not specified in the query or on this parameter, or if a query name is not specified, 1 is the assumed value.
The possible values are:
- *RUNOPT
- If a query definition is being used, the number of lines specified in the query definition is used when this query is run.
- 1
- Indicates that single spacing (no blank lines) is used when the query output is printed.
- 2
- Indicates that double spacing (1 blank line) is used when the query output is printed.
- 3
- Indicates that triple spacing (2 blank lines) is used when the query output is printed.
| Top |
Output file (OUTFILE Parameter)
Specifies the database file (if any) that receives the query output. If no value is specified for this parameter, the library, file, member, and option specified in the query are assumed. If a query is not specified, the file QQRYOUT is created in the default output file library. This library is defined in the query profile or the current library (*CURLIB) if no profile exists. The first member (*FIRST) of this new file is used for the output.
Note: If you did not specify a current library, the QGPL library is used.
If the name specified by the OUTFILE parameter does not exist, the system creates it in the specified library.
There are three parts to this parameter.
Element 1: Database File Name The possible values are:
- data-base-file-name
- Specify the name of the database file that receives the output of the query.
- *RUNOPT
- The database file specified in the query is used to receive the output of the query. The file, library, member, and option do not change. Any values specified for the library, member, and option are ignored.
The name of the database file can be qualified by one of the following library values:
- *RUNOPT
- If specified in the query definition, the output is directed to the library named in the query definition.
- *CURLIB
- The current library for the job is used to locate the database file. If no library is specified as the current library for the job, the QGPL library is used.
- library-name
- Specify the name of the library to be used.
Element 2: Database File Member
The possible member values are:
- *FIRST
- The first member in the file is used to receive the query output.
- *LAST
- The last member in the file is used to receive the query output.
- *RUNOPT
- The member specified in the query is used to receive the query output.
- *ALL
- The output file is a partitioned table, where all members in the file are used to receive the query output. When *ALL is specified for the member, the Element 3 Data option can only be set to *RPLMBR or *ADDMBR. The partitoned table must already exist when the query is run.
- member-name
- The named file member is used to receive the query output.
Element 3: Adding or Replacing Data
The last option specifies whether to put the data in a new database file, replace an existing database file, add a new member, replace an existing member, or add data to an existing member. If no value is specified in the query or in this parameter, or if a query name is not specified, the value *NEWFILE is assumed.
- *RUNOPT
- If a query definition is used, the member option specified in the query definition is the type used when this query is run.
- *NEWFILE
- The output is written to a new database file. This option is not valid when the member name is set to *ALL.
- *RPLFILE
- The output deletes the old file and creates a new file. This option is not valid when the member name is set to *ALL.
- *NEWMBR
- The output is added as a new member. This option is not valid when the member name is set to *ALL.
- *RPLMBR
- The existing member is cleared and the output is then added.
- *ADDMBR
- The output is added to the end of an existing member.
| Top |
Authority (AUT Parameter)
Specifies the authority given to users who do not have specific authority to the output file, who are not on an authorization list, and whose user group has no specific authority to the output file. More information on this parameter is in the CL Reference book, Appendix A.
Note: The authority is assigned only when the output file is created or replaced.
The possible values are:
- *RUNOPT
- If specified in the query definition, the authority named in the query definition is used.
- *LIBCRTAUT
- The public authority for the output file is taken from the value on the CRTAUT parameter of the target library (the library that is to contain the output file). The public authority is determined when the output file is created. If the CRTAUT value for the library changes after the output file is created, the new value does not affect any existing objects.
- *CHANGE
- You can perform all operations on the output file except those limited to the owner or controlled by object existence authority and object management authority. You can change and perform basic functions on the output file. Change authority provides object operational authority and all data authority.
- *USE
- You can perform basic operations on the output file, such as running a program or reading a file. You cannot change the output file. *USE authority provides object operational authority, read authority, and execute authority.
- *ALL
- You perform all operations on the output file except those limited to the owner or controlled by authorization list management authority.
- *EXCLUDE
- You cannot access the output file.
- authorization-list-name
- Specify the name of the authorization list used.
| Top |
Examples
Example 1: Printing Summary Records Only
RUNQRY QRY(LIBX/QRY1) OUTTYPE(*PRINTER)
OUTFORM(*SUMMARY) COPIES(4)
This command runs the query QRY1 located in library LIBX. The report that is produced and printed contains summary records only. Four copies of the report are printed.
Example 2: Running a Default Query
RUNQRY QRYFILE((LIBX/FILE2 *FIRST))
OUTTYPE(*OUTFILE) OUTFORM(*DETAIL)
RCDSLT(*YES) OUTFILE(LIB2/OUT1 MBR4 *NEWMBR)
This command runs a default query and gets the data from the first member of file FILE2 located in library LIBX. Member MBR4 is created as a new member to file OUT1 in library LIB2. Member MBR4 contains the output from the default query. The record selection display is shown to allow you to specify which records from file FILE2 in library LIBX are written to new member MBR4 in file OUT1 in library LIB2. The output contains detail records only.
| Top |
Error messages
None
| Top |