Choosing the synonym definition

The synonym definition is the QMF command or procedure that runs when the user enters the command synonym.

Choosing the synonym on OS/390

An entry in the SYNONYM_DEFINITION column can include:

A RUN command that calls a QMF procedure or query. For example, RUN PROC JONES.SALES_DATA might be a synonym definition for the command synonym COMPUTE MONTHLY_SALES.
A TSO command that calls a CLIST.
A CICS command that starts another CICS transaction.

Your synonym definition can even include both types of commands if the definition runs a QMF linear procedure.

For information about developing complex applications to run in a command synonym, see the Developing QMF Applications manual.

Using a linear procedure in the synonym definition

A linear procedure is a QMF procedure that executes QMF commands sequentially. Your synonym definition can include a linear procedure that does the work of several QMF commands. For example, the procedure in Figure 134 performs the following tasks:

Runs the following query, called SALES_DATA, which creates a report that shows all the customers handled by sales representative number 20:
```
SELECT QUANTITY, CUSTNO
FROM Q.SALES
WHERE SALESREPNO = 20
```
Routes the report from QMF to TSO virtual storage or a CICS temporary queue. In Figure 134, XYZ is the name of the temporary storage queue.
Runs a CICS or TSO procedure to route the report from virtual storage to a predefined print destination. In Figure 134, RPTX is the transaction name. It runs asynchronously with QMF to route output to a destination named REPORTX.

Figure 134. Sample procedure to run using a command synonym

-- Procedure name: SALES_PROC
 RUN QUERY SALES_DATA
 PRINT REPORT (QUEUENAME=XYZ,QUEUETYPE=TS)
 TSO RPTX (FROM=('REPORTX, XYZ'))

Your definition for a synonym that runs this procedure might look similar to the one in Figure 135:

Figure 135. Using a command synonym to run a linear procedure

SYNONYM
VERB           OBJECT           DEFINITION
-----------    ---------------  -------------------
SHOW           SALES            RUN PROC SALES_PROC

If you are using an NLF: Make sure that the QMF commands in the queries, forms, and other objects included in the procedure are translated before you use the command synonym that calls the procedure. Also ensure these components are suitable for the NLF you are using. Unless your procedure sets the DSQEC_NLFCMD_LANG variable to 1, ensure the commands are translated before you use the command synonym.

Choosing the synonym definition on VM

An entry in the SYNONYM_DEFINITION column can include:

A RUN command that calls a QMF procedure or query. For example, RUN PROC JONES.SALES_DATA might be a synonym definition for the command synonym COMPUTE MONTHLY_SALES.
A CMS command that calls a QMF procedure.

Your synonym definition can even include both types of commands if the definition runs a QMF linear procedure.

For information about developing complex applications to run in a command synonym, see the Developing QMF Applications manual.

Using a procedure in the synonym definition

Your synonym definition can include a linear procedure that does the work of several QMF commands. For example, the procedure in Figure 137 performs the following tasks:

Runs the following query, called SALES_DATA, which creates a report that shows all the customers handled by sales representative number 20:
```
SELECT QUANTITY, CUSTNO
FROM Q.SALES
WHERE SALESREPNO = 20
```
Routes the report from QMF to a file.
Runs a QMF procedure to route the report to a predefined print destination. Your definition for a synonym that runs this procedure might look similar to this:

Figure 136. Sample procedure to run using a command synonym ON CMS

-- Procedure name: SALES_PROC
 RUN QUERY SALES_DATA
 CMS FILEDEF DSQPRINT DISK MYPRT FILE A (LRECL 75 BLKSIZE 75 RECFM F
 PRINT REPORT (PRINTER=' '

Figure 137. Using a command synonym to run a procedure

SYNONYM
VERB           OBJECT           DEFINITION
-----------    ---------------  -------------------
SHOW           SALES            RUN PROC SALES_PROC

Choosing the synonym definition on VSE

An entry in the SYNONYM_DEFINITION column can include:

A RUN command that calls a QMF procedure or query. For example, RUN PROC JONES.SALES_DATA might be a synonym definition for the command synonym COMPUTE MONTHLY_SALES.
A CICS command that starts another CICS transaction.

Your synonym definition can even include both types of commands if the definition runs a QMF linear procedure.

For information about developing complex applications to run in a command synonym, see the Developing QMF Applications manual.

Using a linear procedure in the synonym definition

Runs the following query, called SALES_DATA, which creates a report that shows all the customers handled by sales representative number 20:
```
SELECT QUANTITY, CUSTNO
FROM Q.SALES
WHERE SALESREPNO = 20
```
Routes the report from QMF to CICS temporary storage. In Figure 138, XYZ is the name of the temporary storage queue.
Runs a CICS transaction to route the report from temporary storage to a predefined print destination. In Figure 138, RPTX is the transaction name. It runs asynchronously with QMF to route output to a destination named REPORTX.

Figure 138. Sample procedure to run using a command synonym

-- Procedure name: SALES_PROC
 RUN QUERY SALES_DATA
 PRINT REPORT (QUEUENAME=XYZ,QUEUETYPE=TS)
 CICS RPTX (FROM=('REPORTX, XYZ'))

Your definition for a synonym that runs this procedure might look similar to the one in Figure 139:

Figure 139. Using a command synonym to run a linear procedure

SYNONYM
VERB           OBJECT           DEFINITION
-----------    ---------------  -------------------
SHOW           SALES            RUN PROC SALES_PROC

Using variables in the synonym definition

You can use variables in the synonym definition to pass values for like-named variables present in objects (such as queries) named in the definition. For example, Figure 140 shows a definition that passes the value Q.STAFF for the table name, which is evaluated when MYQUERY runs.

Figure 140. Using variables in command synonym definitions

SYNONYM
VERB        OBJECT     DEFINITION
----------  ---------  --------------------------------------
EXECUTE     -          RUN QUERY MYQUERY (&&TABLENAME=Q.STAFF

MYQUERY might look something like:

SELECT * FROM &TABLENAME

Ampersands are doubled in a variable name in the synonym definition because they become single ampersands when QMF executes the RUN command.

Use double ampersands in the synonym definition for all variables except the variable &ALL. &ALL is a special QMF variable that allows you to enter variable values when you enter the synonym, rather than including them in the synonym definition. When you use the variable &ALL in a synonym definition, QMF uses as variable values any information you enter to the right of the synonym. You can use the &ALL variable to show where the information is located within the synonym definition.

The synonym definition in Figure 141 shows an example of a synonym defined using &ALL.

Figure 141. Using the variable &ALL in a command synonym definition

SYNONYM
VERB        OBJECT     DEFINITION
----------  ---------  ------------------------
SHOW_INFO   -          RUN QUERY STAFFQUERY (&ALL)

The query named STAFFQUERY might look something like the following:

SELECT * FROM Q.STAFF
WHERE DEPT=&DEPT and JOB=&EMPLOYEE_JOB

After activating the SHOW_INFO synonym defined in the preceding example, you can enter the following statement from the QMF command line to display information about all the managers in Department 10:

SHOW_INFO &DEPT=10 &EMPLOYEE_JOB='MGR'

Rules for &ALL

When you use the variable &ALL in a synonym definition:

Use &ALL only once in a synonym definition.
Always write &ALL in uppercase.
Never follow &ALL with a number or letter.
Any value you substitute for &ALL must be syntactically correct when QMF evaluates the entire command. For more information on syntax of QMF commands, see the QMF Reference manual.

If a user does not supply a value following the command synonym, QMF substitutes a null value for &ALL. In the synonym definition shown in Figure 141, QMF prompts the user for values for the &DEPT and &EMPLOYEE_JOB variables if the user enters SHOW_INFO by itself on the command line.

Keying information into the SYNONYM_DEFINITION column

Follow these rules when keying your synonym definitions into the synonym table:

Add single quotes around a variable in your synonym definition.
Single quotes around a variable eliminate the need for the user to add quotes to the command synonym when running a query. For example, &ALL has single quotes in this synonym definition:
```
RUN MYQUERY (&&NAMEVALUE='&ALL'
```
If you search for the name O'BRIEN, you do not need to enter 'O'BRIEN', because QMF does this for you.
Enter base verbs and keywords in uppercase.
Literal information in the synonym definition is not converted to uppercase.
Qualify all object names if their owners are different from the SQL authorization ID of the user who uses the synonym.
QMF leaves names unqualified when searching for a synonym that contains the object name specified. For example, if your synonym definition includes a query named MY_SALES owned by user ID JONES, ensure that the object name in the synonym definition reads JONES.MY_SALES. Otherwise, JONES is the only user that can use that command synonym.
Use only capital letters for letters that lie outside of delimited identifiers.
If QMF converts user input (the synonym) to uppercase and the synonym definition is in lowercase, QMF cannot find the synonym definition that matches the synonym the user entered. The CASE value of the user's QMF profile controls whether input is converted to uppercase. Use the SET PROFILE command to change the CASE value. This command is explained in the QMF Reference manual.

[ Previous Page | Next Page | Contents | Index ]