Drag & drop with REXX

Dragging and dropping an object on a REXX program is an area that concerns many REXX programmers, particularly those more familiar with command line, or "ugly mode" REXX programming. Listing 1 contains a simple REXX program that can be used to illustrate each of the cases I am going to describe. You might want to take this opportunity to temporarily create a program object on your Desktop which can be used to launch the 9505LS01 REXX program in Listing 1. At the same time, create a shadow of some test file on your Desktop in proximity to the program object so you can conveniently drop it on the program object to verify the test results. Any reamdme.doc file would be a good choice. In the explanations I use, the full file system name of the data file object that I dropped on the program object is K:\text\readme.doc.

A simple method of creating a shadow of a file is to open either an icon or details view of a drive or folder and drag the file's icon to the Desktop while at the same time holding down <Ctrl> and <Shift>.

Listing 1 - 9505ls01

   /*-------------------------------------------------------------*\
   |  9505LS01.CMD - Used to test the handling of dropped objects  |
   \*-------------------------------------------------------------*/
   parse arg string     /* assign calling parameters to string */
   number = ARG()       /* get number of parameters passed */

   /* echo number, length, and value of calling parameters */
   say 'Nbr =' number                     ||,
       ',  Length = ' || LENGTH( string ) ||,
       ',  Value = '  || string


   /* show hexadecimal value of calling parameters */
   if LENGTH( string ) > 0 then
      do
         say "'" || C2X( string ) || "'x"
      end
   say 'Press <Enter> to end program'
   pull reply           /* dummy read just to hold screen */
   exit

To create the program object, open the Templates folder (normally located within the OS/2 System folder) and drag a Program object template to your Desktop. This will result in a settings notebook (Figure 2) to be created and opened on the Desktop for the new program object. The required Path and file name: field must contain the full file system name (drive, path, file name, and file extension) of your newly created program - in this case 9505ls01.cmd preceded by the drive and path name where you created the REXX program. The optional Parameters: field is the field that controls what will be passed to the REXX program when it is launched.

Figure 2

The parameters that are passed to the REXX program are in the same format as they would be if the program was launched from the command line with the parameters following the program name on the command line. Since OS/2 REXX treats all command line data as a single string, dropping an object on a program object will cause the parameter data to be treated in a consistent manner. Regardless of how many tokens exist in the parameters passed to the program, the ARG() built-in function will always return a value of 1. With nothing specified in the Parameters: field in the settings notebook, the full file system name (drive, path, and file name) are passed to the REXX program. In the case of my example this string would be "K:\TEXT\README.DOC" (without the quotes). The case of the parameter string will be the same as it is in the file's directory entry. For FAT drives the file system name will always be uppercase. For HPFS drives the case may be mixed.

Table 4, copied from the third edition of the REXX Reference Summary Handbook, contains a list of substitution values that my be used singly or in combination in the Parameters: field. By including any of these substitution values, any portion of the dropped object's file system name can be passed to the REXX program as a parameter. For example, by including just a percent sign (%) in the Parameters: field, the default value of the full file system name is inhibited. By including %**D just the drive letter followed by a colon (:) is passed to the REXX program. Dropping readme.doc file icon on the REXX program and including the substitution values %**D %**P %**N %**E in the Parameters: field results in the REXX program starting with a parameter string of "G: G:\TEMP\ README DOC" (without the quotes).

Additionally, a left and right bracket pair ([ ]) can be inserted in the Parameters: field to cause a dialogue box, like the one shown in Figure 3, to popup when the file object is dropped on the REXX program object. The title of the dialogue box will always be "Specify Parameters" and the file system name of the program object will be on line one.

Figure 3

Any characters which appear between the brackets will show on line two of the dialogue box as a prompt. The substitution values may also be used both outside of and within the prompt string. If a prompt is used in combination with other characters in the Parameters: field, any characters entered into the list entry field of the dialogue box will be passed to the REXX program in the same relative position that the bracketed prompt string appeared. For example, using our sample file and program object with a Parameters: field of 1[234]5, line two of the dialogue box will be 234. If you key abc and select Open, the string "1abc2 K:\TEXT\README.DOC" (without the quotes) will be passed to the REXX program.

There appears to be some undocumented combinations of characters that have special meanings when used in the Parameters: field. One example is a string containing a carat and a percent sign (^%). This string results in a line feed character ('0A'x) being passed to the REXX program. I will leave it to the readers to detect any other undocumented values. You are welcome to Email them to me and I will include them in a future column.

REXX Happening