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>)

(for example, C:\bin\mytools). (Object ids will be explained later)
 * 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, ) or a file system path
 * 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 ) 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 '', 'OPEN=DEFAULT;' Can be used to change the title of an object: /* change Information folder name */ call SysSetObjectData '', '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 . 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 , 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 . 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 , make it a shadow of an object.   Desktop     Startup folder    OS/2 System folder     Templates folder    System Setup folder      Information folder    Drives folder   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. 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.

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 /* Set Clipboard Private */ result = SysIni('USER', 'WINOS2', 'PM_ClipboardSupport', '1']]'00'x)
 * Key PM_ClipboardSupport
 * Value 0 - Public (share with WIN-OS/2)
 * Value 1 - Private (non-share with WIN-OS/2)
 * Example: