Passing variable values to an initial procedure

When you supply the name of an initial procedure on the DSQSRUN parameter, you can also supply values for one or more variables contained in the procedure.

Follow these rules when you specify variables for the DSQSRUN parameter:

Put parentheses around the variable parameter list.
Precede the variable name with an ampersand, and ensure that the string is in a variable_name=value format.
Ensure that the combined total of characters for the procedure name and the variable parameter list is 98 characters or less.
Separate the variable parameter specifications using a single comma, one or more blanks, or a combination of a comma and blanks.

The following table lists the number of ampersands required to use a variable in each environment.

Table 1. Required number of ampersands preceding program variables
Environment	Number of additional ampersands	Example
CICS®	0	&variable=value
TSO without ISPF	0	&variable=value
TSO with ISPF	1	&&variable=value
TSO without ISPF using CLISTs	2	&&&variable=value
TSO with ISPF using CLISTs	3	&&&&variable=value

When you specify the name of an initial procedure, QMF issues a RUN PROC command that runs the procedure. When you use variables in your procedure, the values you supply for these variables must conform to the syntax used for passing variables on a RUN command.

For example, suppose you frequently need two pieces of information about employees in your organization. One piece of information is the name of the employee, and the other varies. You might define a query that returns values for the NAME column and uses a variable for the name of the other column. The following figure shows an example query and procedure. The figure also shows how to pass a value for the variable when you enter the DSQSRUN parameter, and shows the resulting RUN PROC command that QMF issues.

Figure 1. Passing a column name on the DSQSRUN parameter

Query (JONES.QUERY2): SELECT NAME, &COL FROM Q.STAFF
Procedure (JONES.PROC2): RUN QUERY JONES.QUERY2 (&&COL=&COL
DSQSRUN parameter: QMFn I=JONES.PROC2(&COL=YEARS)
Resulting RUN command: RUN PROC JONES.PROC2 (&COL=YEARS)

The next figure shows a similar example, but instead of passing one column name to the procedure, it allows you to pass several, which return the employee's name, the department, and the employee's salary.

Figure 2. Passing several column names on the DSQSRUN parameter

Query (JONES.QUERY3): SELECT &COLS FROM Q.STAFF
Procedure (JONES.PROC3): RUN QUERY JONES.QUERY3 (&&COLS=&COLS
DSQSRUN parameter: QMFn I=JONES.PROC3(&COLS=((DEPT,NAME,SALARY))
Resulting RUN command: RUN PROC JONES.PROC3(&COLS=((DEPT,NAME,SALARY)))

The next four examples show how to pass information that you normally supply after the WHERE keyword in a query.

These examples contain character strings, which require special syntax because of how QMF evaluates the values when it processes the RUN PROC command. Special characters (commas, blanks, parentheses, double or single quotation marks, apostrophes, and equal signs) can also be included in the string, as shown in the examples.

The first of these four examples shows a query that returns the names and employee numbers of all the managers in an organization. When you pass the character string MGR on the DSQSRUN parameter, be sure to enclose the value in single quotation marks.

Figure 3. Passing a character string within single quotations marks on the DSQSRUN parameter

Query (JONES.QUERY4): SELECT JOB, NAME, ID FROM Q.STAFF WHERE JOB=&JOB
Procedure (JONES.PROC4): RUN QUERY JONES.QUERY4 (&&JOB=&JOB
DSQSRUN parameter: QMFn I=JONES.PROC4(&JOB='MGR')
Resulting RUN command: RUN PROC JONES.PROC4 (&JOB='MGR')

The second of the four examples shows how to pass variable values that contain commas. Enclose the value SAN JOSE, CA in single quotation marks because it contains a comma.

Figure 4. Passing a comma within a string on the DSQSRUN parameter

Query (JONES.QUERY5): SELECT * FROM Q.APPLICANT WHERE ADDRESS=&CITY
Procedure (JONES.PROC5): RUN QUERY JONES.QUERY5 (&&CITY=&CITY
DSQSRUN parameter: QMFn I=JONES.PROC5(&CITY='SAN JOSE, CA')
Resulting RUN command: RUN PROC JONES.PROC5 (&CITY='SAN JOSE, CA')

The third of the four examples with character strings shows how to pass variable values that contain single quotation marks (for example, an apostrophe in a name). When you pass the value on the DSQSRUN parameter, be sure to enclose the value in single quotation marks and use two single quotation marks for the apostrophe instead of one.

Figure 5. Passing an apostrophe as part of a string on the DSQSRUN parameter

Query (JONES.QUERY6): SELECT * FROM Q.STAFF WHERE NAME=&NAME
Procedure (JONES.PROC6): RUN QUERY JONES.QUERY6 (&&NAME=&NAME
DSQSRUN parameter: QMFn I=JONES.PROC6(&NAME='O''BRIEN')
Resulting RUN command: RUN PROC JONES.PROC6 (&NAME='O''BRIEN')

The last of the four examples shows how to pass more than one variable value on the RUN command.

Figure 6. Passing multiple variable values on the DSQSRUN parameter

Query (JONES.QUERY7): SELECT * FROM Q.STAFF WHERE DEPT IN &DEPT AND JOB = &JOB
Procedure (JONES.PROC7): RUN JONES.QUERY7 (&&DEPT=&V1 &&JOB=&V2
DSQSRUN parameter: QMFn I=JONES.PROC7(&V1=(((10,38))) &V2='MGR')
Resulting RUN command: RUN PROC JONES.PROC7(&V1=(((10,38))) &V2='MGR')