REXXUTIL Information and Samples

by Michael Lamb

The following attempts to better explain some of the powerful features provided by OS/2 V2's dynamic link library; REXXUTIL.DLL (Rexx utility functions). REXXUTIL functions are described in the online 'REXX Information' reference and the 'OS/2 2.0 Technical Library Procedures Language/2 REXX Reference' publication (order number S10G-6268). The information following is intended to provide a more detailed description of some of the functions.

Plans for this information

Much of this file has changed since the first few attempts at compiling useful REXXUTIL information. Plans are to place this information out on an IBM Internal FORUM, (REXXOS2 FORUM) and the OS2REXX CFORUM which makes its way out into the external customer world. Hopefully within a month or so of making it available I've received any corrections/omissions from both IBMer's and customers. Thereafter I plan to create an OS2EWS package that will contain this text information with the sample CMD files as separate files. Also I plan on including an INF formatted file of the information. I really do want the information to be as accurate as possible before creating the INF file so please report to me any items of omission or error.

Publications

One should realize that many of the functions provided by REXXUTIL have origins with Presentation Manager Winxxx calls. These publications are helpful and be reviewed for more information:

S10G-6265 OS/2 PM Programming Reference Vol - 2

Contains all the Winxxx calls, the Workplace Shell classes, and their _wpxxx messages. Also this is available as an online doc that comes with the OS/2 Toolkit.

S10G-6309 OS/2 System Object Model Reference

Also an online doc that comes with the OS/2 Toolkit.

GBOF-2254 OS/2 Technical Redbooks (series of technical documents)

GG24-3732 OS/2 V2 Volume 3: Presentation Manager & WPS

GG24-3774 OS/2 V2 Volume 4: Application Development

ZB35-5100 The REXX Language - A Practical Approach to Programming

ISBN 0-13-780651-5

Functions

Some of the functions used/explained herein:

SysIni

Using REXXUTIL's SysIni function one can modify many settings of the WorkPlace Shell as well as change other applications settings that make use of *.INI files such as the system OS2.INI and OS2SYS.INI.

SysCreateObject

(PM WinCreateObject - Create Workplace Object):Using REXXUTIL's SysCreateObject function one can create various objects; like folders, programs, and shadow objects using Rexx. This section for the most part includes parameter information which was gathered together from various sources of information.

SysSetObjectData

(PM WinSetObjectData - Set Object Data):Using REXXUTIL's SysSetObjectData function one can change an objects characteristics (of an already created object, if you know its objectid).

SysDestroyObject

(PM WinDestroyObject - Destroy Workplace Object):Using REXXUTIL's SysDestroyObject one can delete an object created if you know its objectid.

Misc Notes

If one views the *.RC files located in your bootdrive:\OS2 directory you can learn a lot about the various INI settings and folder structure. Review INI.RC and INISYS.RC files, they are used to create your OS2.INI and OS2SYS.INI files. (Note in the *.RC files "?:" is used to indicate the boot drive)

Some of REXXUTIL's functions are only available when using the very latest REXX20 PACKAGE which consists of the very latest REXX fixes and enhancements for GA OS/2 V2.0. Should you have problems running any of the sample programs you should make sure your system has the vary latest REXX20 updates. In addition to the REXX fixes, various OS/2 V2 base fixes may be needed as well. You may need to install/apply the latest 2.0 Service Pack, or even OS/2 2.1 in order for some of the operations to behave properly.

If anyone discovers other parameters or other "hidden" features of any of the functions discussed, please share your discovery. I'll try to update the information as I receive it.

Thanks...

Michael Lamb, Workstation Technical Support, ISSC - MHV Solution Center

Change Log

04/30/92 - Added information about DuplicateFlag parm
         - Added more setup string information from manuals
06/02/92 - Added information about breaking Title line character "^"
         - Added information about adding multiple DOS_DEVICE statements
         - Added code to SHADOW.CMD to make shadow object of a file
!!NOTE!! - The REXXOS2 fixes are required to make some of
           the newer samples work properly.
06/30/92 - Added information regarding two new REXXUTIL functions:
           SysSetObjectData and SysDestroyObject, also two new
           samples STARTDOS, BOOTDOS (Thanks to Rick McGuire)
07/13/92 - Reorganized the way the material is presented. Also added more
           sample Rexx routines REBUILD, OBJCLASS and LPTADD, descriptions
           follow. Also changed parm CONCURRENTVIEW to CCVIEW (Thanks
           Dan Kehn, Felix Sawicki)
07/15/92 - Updated entire document as I mistakenly truncated it at 80
           characters. Rewrote some sample Rexx routines so they do not
           extend beyond 80 characters. Also updated the SysSetObjectData
           description to show how can open an object (Thanks Rick). Added
           information about creating multi-line titles, carat works for
           two line titles but not more than 2.
           New samples, OBJECTID and FONTS included, descriptions follow.
07/29/92 - Corrected an error I made when I broke the setup lines into
           multiple lines. I needed to add ]]'s to make sure they
           concatenated without spaces (Thanks Rick). Also added
           information regarding changing some System Settings (added
           new section after sample Rexx code). Also added warning
           in REBUILD.CMD sample about replacing Folder objects. Also
           added new sample ICONRES.CMD which builds a folder containing
           many of the OS/2 V2 installed icons using system DLL files.
01/30/93   Added to some examples the use of SysDestroyObject to clean up
           after creating objects, also added the syntax for the call.
           Changed REBUILD.CMD sample to used 'U' for updateifexists as
           the duplicateflag to prevent problems. Added warning about
           the 'R' duplicateflag parameter to field description.
           Added information about changing Background tab, Change color
           button values. Changed OBJECTID.CMD to enclose results in
           double quotes to easier distinguish results.
           Changed descriptions of calls to better match what's found in the
           toolkit documentation for the Winxxx calls.
04/11/93   Added some information in ASSOCTYPE, ASSOCFILTER section.
           Added new PROGTYPE values. Added ICONVIEWPOS information.
07/04/93   Too many changes to note. Lots having to do with OS/2 V2.1

REXXUTIL Functions

This section contains information on the some of the functions of the REXXUTIL library that comes with OS/2 REXX.

SysCreateObject

Create a new instance of an object class

Function: SysCreateObject

Syntax:

result=SysCreateObject(classname, title, location <,setup>, <,duplicateflag>)

classname

The name of the class of which this object is a member.

title

The object title, as it is to appear when displayed on the user interface underneath an icon or on the title bar of an open object. (Note this can be changed later using the TITLE keyword)

location

The object location. This can be specified as either an object ID (for example, <WP_DESKTOP>) or a file system path

(for example, C:\bin\mytools). (Object ids will be explained later)

setup

A WinCreateObject setup string. Described more later on.

duplicateflag

This parameter indicates what action should be taken when the Setup string specifies an object ID, and an object with that object ID already exists. If the setup string does not give an object ID, another object will be created.

result

The return code from WinCreateObject. This returns 1 (TRUE) if the object was created and 0 (FALSE) if the object was not created.

SysSetObjectData

Alter the settings of an existing object.

Function: SysSetObjectData

Syntax:

result=SysSetObjectData(name, setup)

name

The object name. This can be specified as an object id (for example <WP_DESKTOP>) or as a fully qualified file name.

setup

A WinCreateObject setup string. Described more later on.

result

The return code from WinSetObjectData. This will return 1 (TRUE) if the object was updated and 0 (FALSE) if the object was not updated.

Can be used to open an instance of an object:

/* open up the system folder */
call SysSetObjectData '<WP_OS2SYS>', 'OPEN=DEFAULT;'

Can be used to change the title of an object:

/* change Information folder name */
call SysSetObjectData '<WP_INFO>', 'TITLE=InfoFolder'

See the description of the SysCreateObject location and setup strings following for an explanation of the parameters.

SysDestroyObject

Delete an existing workplace object, or file.

Function: SysDestroyObject

Syntax:

result=SysDestroyObject(name)

name

The object name. This should be specified as an object id, for example <WP_CMDREF>. It can also be a fully specified file name.

result

The return code from WinDestroyData. This will return 1 (TRUE) if the object was destroyed and 0 (FALSE) if the object was not destroyed.

See the description of the SysCreateObject location parameter following for an explanation of the object name. See the OBJECTID.CMD sample for a way to determine the objectid's the system knows about.

Parameters Explained

Parameters to the functions are now explained in more detail.

classname

A registered object class defined to the system. Of particular interest are the WPFolder/WPProgram/WPShadow classes. Note using the sample Rexx code included in the SysQueryClassList function help screen one can list all of the registered classes:

call SysQueryClassList "list."
do i = 1 to list.0
   say 'Class' i 'is' list.i
end

title

The objects title you want to use. If you wish to break the title line you use a comma "," as the line break character. However, there were problems with this and it may or may not work depending on whether you have the latest REXX and OS/2 V2 fixes installed. You may instead decide to use a hex 0A character (line-feed) in the string to separate lines.

Rexx example: Note: x2c is Rexx's hex to character function.

title='First'x2c(A)'Second'x2c(A)'Third'

Note if you wish to use the special characters; comma or semi-colon in the string, prefix the character with the carat symbol.

Example title, you want:

] My Activities     ]   you would use...
] December 25, 1992 ]     title='My Activities,December 25^,1992'

location

The object's location can be specified as either an existing object id, for example <WP_DESKTOP>, or alternatively a fully qualified file name of any file or directory.

An object id string must always start with the '<' character and be terminated by the '>' character and is thus an invalid file system name.

By looking at your \OS2\INI.RC file you can see a use of many object ids such as <WP_DESKTOP>. If this is used as a location then your object will be placed on the WorkPlace Shell desktop.

If you are creating an object you should make sure you use the OBJECTID setup string parameter and give that object a unique object id. We'll see how this works later.

HINTS: Here are some predefined object ids of system folders. Also if you are thinking of placing an object in the Startup Folder <WP_START>, make it a shadow of an object.

<WP_DESKTOP>   Desktop
<WP_START>     Startup folder
<WP_OS2SYS>    OS/2 System folder
<WP_TEMPS>     Templates folder
<WP_CONFIG>    System Setup folder
<WP_INFO>      Information folder
<WP_DRIVES>    Drives folder
<WP_NOWHERE>   Hidden folder
<WP_PROMPTS>   Command Prompts folder
<WP_TOOLS>     Productivity folder
<WP_GAMES>     Games folder

Some other common OS/2 folder objectids:

<MAH_FOLDER>   Mahjongg folder
<MMPM2_FOLDER> Multimedia folder
<MMPM2_SOUNDS> Multimedia Sound Bites folder
<MMPM2_MOVIES> Multimedia Movies folder
<TK_TOOLKIT>   Toolkit 2.1 folder
<TK_DEVINFO>   Toolkit Information folder
<TK_DEVTOOLS>  Development Tools folder
<TK_CSAMPLE>   Sample Programs folder

setup

This field needs the most explaining. Each object class, WPProgram, WPFolder, etc, documents its setup string keynames and parameters. A larger section follows that details many of the available keynames and parameters. The setup string contains a series of "keyname=value" pairs, that change the behavior of the object. "keynames" are separated by semicolons, and "values" are separated by commas.

"key=value;key2=value1,value2;"

If you want a literal comma or semicolon inside one of your fields you must precede the comma/semi-colon with a carat as in the following:

^,   A literal comma
^;   A literal semicolon

Note that ALL setup string parameters have safe defaults, so it is never necessary to pass unnecessary parameters to an object.

(Note: The setup string was limited to a total length of 255 bytes in the 2.0 GA code, this limitation is removed if the Service Pack is applied or you are using OS/2 2.1) (APAR PJ02271)

duplicateflag

There are three possible values for this parameter:

FailIfExists

No object should be created if an object with the given object already exists. This is the default and maps to the PM creation flag, CO_FAILIFEXISTS

UpdateIfExists

If an object with the given object ID already exists, the existing object will be updated with the new setting information. Maps to the creation flag, CO_UPDATEIFEXISTS. If the object does not exist, it is created.

ReplaceIfExists

If an object with the given object ID already exists, the existing object should be replaced. Maps to the PM creation flag, CO_REPLACEIFEXISTS.

WARNING: Be careful using the 'R' ReplaceIfExists value. Any attempt to rebuild an object first deletes any object that is using that same <objectid>. This can be useful if you want to restore an object back to its original installed state. This can also be bad since if you rebuild a folder it first deletes all objects in it since those objects are tied to the folder object.

Note: Only the first character is required/examined, i.e. F, R, or U

Setup Strings

Using WPFolder and WPProgram classes in your SysCreateObject call you can build folder and program objects. What follows are setup string parameters. Their various key names, values, and a short description follow each item.

An instance of each class is created initially by the system in its template form. It has the title "Folder" / "Program", respectively, and resides in the systems "Templates" folder.

REXX CMD Samples

Listing of sample programs

FOLDER.CMD

Creates a folder and program objects in the folder

SHADOW.CMD

Creates shadows of objects

FLDSHAD.CMD

Creates a folder, then program object in the folder, then place a shadow of the program object on the desktop.

MKSHAD.CMD

Creates a shadow object of an objectid, file or drive/directory.

STARTDOS.CMD

Starts a DOS program using specific DOS VDM settings.

BOOTDOS.CMD

Starts a DOS session, booting from a specific DOS image with specific DOS VDM settings.

REBUILD.CMD

Allows one to rebuild OS/2 system objects, kinda like MAKEINI does.

LPTADD.CMD

Code using SysIni to add LPT4-9 ports.

OBJECTID.CMD

Code using SysIni to list OBJECTIDs known to the WorkPlace Shell

FONTS.CMD

Code using SysIni to list installed fonts and verify their existence.

ICONRES.CMD

Code building a folder containing many of the various icons found in installed DLL files for OS/2 V2. Demonstrates use of setup string parameter ICONRESOURCE.

SWAPEDIT.CMD

Code that allows you to make the Enhanced Editor (EPM) the default open action for most data objects instead of the OS/2 Enhanced Editor (E).

OPENWPS.CMD

Code that allows you to open up an objectid or directory using views you specify.

Code Fragments

System Settings

During our attempts at customizing the shell using REXXUTILs for newly created workstations we discovered many items can be controlled. Our first attempt was to turn off the default setting for Workplace Shell Print Screen. We wanted it disabled instead of enabled (saves our customers from accidentally printing the workplace shell screen contents :-)

From there we learned other items could be changed:

Remember the basic SysIni call is:

result = SysIni(inifile, app, key, val)

Note

Some items if changed did not seem to take effect until the next reboot.

To see the menu items that can be changed go to:

OS/2 System / System Setup / System, Confirmation tab

/* Confirm on folder delete                      0=not checked 1=checked */
res=SysIni('USER', 'PM_ControlPanel', 'ConfirmSubDelete', '0']]'00'x)
/* Confirm delete                                0=not checked 1=checked */
res=SysIni('USER', 'PM_ControlPanel', 'ConfirmDelete', '0']]'00'x)
/* Confirm on rename of files with extensions    0=not checked 1=checked */
res=SysIni('USER', 'PM_ControlPanel', 'ConfirmRenameFilesWithExt', '0']]'00'x)
/* Confirm on copy, move, create shadow          0=not checked 1=checked */
res=SysIni('USER', 'PM_ControlPanel', 'ConfirmCopyMoveEtc', '0']]'00'x)
/* Display progress indication dialog            0=not checked 1=checked */
res=SysIni('USER', 'PM_ControlPanel', 'DisplayProgressInd', '0']]'00'x)

Title

To see the menu items that can be changed go to:

OS/2 System / System Setup / System, Title tab

/* Title clash */
/* Prompt for appropriate action  16 */
/* Auto-rename object             2  */
/* Replace existing object        8  */
result = SysIni('USER', 'PM_ControlPanel', 'NameClash', '16']]'00'x)

Button appearance for windows

To see the menu items that can be changed go to:

OS/2 System / System Setup / System, Window tab

/* Hide button = 1 plus hex 0 */
result = SysIni('USER', 'PM_ControlPanel', 'MinButtonType', '1']]'00'x)
/* Minimize button = 2 plus hex 0 */
result = SysIni('USER', 'PM_ControlPanel', 'MinButtonType', '2']]'00'x)

Animation

/* Enabled = hex 01 00 00 00 */
result = SysIni('USER', 'PM_ControlPanel', 'Animation', '01000000'x)
/* Disabled = hex 00 00 00 00 */
result = SysIni('USER', 'PM_ControlPanel', 'Animation', '00000000'x)

Global WIN-OS2 Settings

With OS/2 V2.1 you are able to control certain WIN-OS/2 session properties for all Windows applications. You can locate this new control by going to:

OS/2 System / System Setup / WIN-OS/2 Setup

The changes you make here will be reflected for all newly created objects that use WIN-OS/2 settings. No setup string exists to change WIN_DDE, nor WIN_CLIPBOARD on a program by program basis.

3.1 Session tab

Key PM_Global31SessionType

• Value 15 - WIN-OS/2 Window separate session (3.1 Standard)
• Value 16 - WIN-OS/2 Window (3.1 Standard)
• Value 17 - WIN-OS/2 Window separate session (3.1 Enhanced Compatibility)
• Value 18 - WIN-OS/2 Window (3.1 Enhanced Compatibility)
• Value 19 - WIN-OS/2 Full screen (3.1 Enhanced Compatibility)
• Value 20 - WIN-OS/2 Full screen (3.1 Standard)

Example:

/* Set global session type to WIN-OS/2 Full screen (3.1 Standard) */
result = SysIni('USER', 'WINOS2', 'PM_Global31SessionType', '20']]'00'x)

WIN-OS/2 Settings button

Key PM_GlobalWin31DataExchange

• Value 0 - WIN_DDE On WIN_CLIPBOARD On
• Value 4 - WIN_DDE Off WIN_CLIPBOARD On
• Value 8 - WIN_DDE On WIN_CLIPBOARD Off
• Value 12 - WIN_DDE Off WIN_CLIPBOARD Off

Example:

/* Set DDE on, Clipboard off */
result = SysIni('USER', 'WINOS2', 'PM_GlobalWin31DataExchange', '8']]'00'x)

Key PM_GlobalWindows31Settings

• Need to supply the text of DOS, WIN settings separated by nul 0 character AND the string ends with nul 0 nul 0

Example:

/* Default settings */
setting='DPMI_MEMORY_LIMIT=64']]'00'x]],
        'PROGTYPE=PROG_31_STD']]'00'x]],
        'KBD_ALTHOME_BYPASS=1']]'00'x]],
        'VIDEO_SWITCH_NOTIFICATION=1']]'00'x]],
        'VIDEO_8514A_XGA_IOTRAP=0']]'00'x]]'00'x
result = SysIni('USER', 'WINOS2', 'PM_GlobalWindows31Settings', setting)

Data Exchange tab

Data exchange between OS/2, DOS and WIN-OS/2 sessions

1. Dynamic data exchange Key PM_DDESupport

- Value 0 - Public (share with WIN-OS/2)

- Value 1 - Private (non-share with WIN-OS/2)

- Example:

      /* Set DDE Private */
      result = SysIni('USER', 'WINOS2', 'PM_DDESupport', '1']]'00'x)

2. Clipboard

• Key PM_ClipboardSupport
  • Value 0 - Public (share with WIN-OS/2)
  • Value 1 - Private (non-share with WIN-OS/2)
  • Example:

       /* Set Clipboard Private */
       result = SysIni('USER', 'WINOS2', 'PM_ClipboardSupport', '1']]'00'x)