Contents of the CRTOBJ.TXT file

Subject: REXXUTIL Information and Samples

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

One should realize that many of the functions provided by REXXUTIL haveorigins with Presentation Manager WinXXX calls. The 'OS/2 TechnicalLibrary Presentation Manager Programming Reference Vol2' publication(order number S10G-6265) can be reviewed for more information.

Some of the functions used/explained:

SysIni:Using REXXUTIL's SysIni function one can modify many settings of the WorkPlaceShell as well as change other applications settings that make use of *.INIfiles 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 themost part includes parameter information which was gathered together fromvarious sources of information.

SysSetObjectData: (PM WinSetObjectData - Set Object Data)Using REXXUTIL's SysSetObjectData function one can change an objectscharacteristics (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 youknow its objectid.

Misc Notes:If one views the *.RC files located in your bootdrive:\OS2 directory youcan 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.INIand OS2SYS.INI files.

Some of REXXUTIL's functions are only available when using the very latestREXX20 PACKAGE which consists of the very latest REXX fixes and enhancementsfor OS/2 V2. So should you have problems running any of the sample programsyou should make sure your system has the vary latest REXX20 updates.

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.

This append consists of multiple pieces of information:

1) Large block of text containing information that pertains to the subject. (TEXT INFORMATION)2) Sample Rexx code, some complete programs, others code fragments: - (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. - (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, 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. - 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.3) Code Fragments - (SYSSET) Shows using SysIni to toggle various System Settings

location: The object location. This can be specified as either a descriptive path (for example, OS/2 System Folder\System Configuration) or a file system path (for example, C:\bin\mytools).

setup: A WinCreateObject setup string.

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, a duplicate 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.

Purpose: Create a new instance of an object class.

-- Help information regarding the SysSetObjectData function of REXXUTIL --

Function: SysSetObjectDataSyntax:result=SysSetObjectData(name, setup)

name: The object name. This can be specified as an object id (for example ) or as a fully specified file name.

setup: A WinCreateObject setup string.

Purpose: Alter the settings of an existing object. Can also be used to open an instance of an object: /* open up the system folder */ call SysSetObjectData '', 'OPEN=DEFAULT;'

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

-- Help information regarding the SysDestroyObject function of REXXUTIL --

Function: SysDestroyObjectSyntax:result=SysDestroyObject(name)

name: The object name. This can be specified as an object id (for example ) or as a fully specified file name.

Purpose: Destroys an existing object.

See the description of the SysCreateObject location parameterfollowing for an explanation of the object name.

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: Easy one, the objects title you want to use. If you wish to break the title line use the carat "^" symbol in the title. Ex. 'First line^Second Line' This works to break a title into two lines. However to break a title into more than two lines you need to separate the title lines with a hex 0A (line-feed) character. Rexx example: h0A='0A'X title='First'h0A'Second'h0A'Third'

location: The objects location can be specified as either a descriptive path (for example, OS/2 System Folder\System Configuration) or a file system path (for example, C:\bin\mytools). However by looking at the INI.RC file one can see a use of other "locations", such as . If this is used as a location then your object will reside on the WorkPlace Shell desktop. If you are creating a folder or program object you should make sure you use the setup string option and give that folder a unique OBJECTID. 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. The Desktop. The Startup folder. The System folder. The Templates folder. The System Setup folder. The Information folder. The Drives folder. The hidden folder.

setup: This field needs the most explaining, a larger section following details many of the available setupstring parameters. The setupstring field contains a series of "keyname=value" pairs separated by semi-colons that change the behavior of an object. Each object class documents its keynames and the parameters it expects to see.

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 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. UpdateIfExists - If an object with the given object ID already exists, the existing object should be updated with the new information. Maps to the creation flag, CO_UPDATEIFEXISTS. (Only the first character is required/examined, i.e. F, R, or U)

ALL parameters have safe defaults, so it is never necessary to passunnecessary parameters to an object.

What follows are both WPFolder and WPProgram setup string parameters. Their various key names, values and a short description follow each item. The <> item is there to give you an idea of what Workplace Shell settings "page" you would find this information on.

************************************WPFolder setup string parms************************************KEYNAME VALUE Description-----------------------------------------------------------------------------<>OPEN ICON Open icon view when object is created. TREE Open tree view when object is created. DETAILS Open details view when object is created.ICONVIEW s1[,s2,...sn] Set icon view to specified style(s).TREEVIEW s1[,s2,...sn] Set tree view to specified style(s).DETAILSVIEW s1[,s2,...sn] Set details view to specified style(s).(styles) FLOWED flowed list items NONFLOWED non-flowed list items NONGRID non-gridded icon view NORMAL normal size icons MINI small icons INVISIBLE no icons LINES lines in tree view NOLINES no lines in tree view<>BACKGROUND filename Sets the folder background. filename is the name of a file in the \OS2\BITMAP directory of the boot drive.<>WORKAREA YES Make the folder a Workarea folder<>MINWIN HIDE Views of this object will hide when their minimize button is selected. VIEWER Views of this object will minimize to the minimized window viewer when their minimize button is selected. DESKTOP Views of this object will minimize to the Desktop when their minimize button is selected.VIEWBUTTON HIDE Views of this object will have a hide button as opposed to a minimize button. MINIMIZE Views of this object will have a minimize button as opposed to a hide button.CCVIEW YES New views of this object will be created every time the user selects open. NO Open views of this object will resurface when the user selects open.<>ICONFILE filename This sets the object's icon.ICONRESOURCE id,module This sets the object's icon. 'id' is the identity of an icon resource in the 'module' dynamic link library (DLL).ICONPOS x,y This sets the object's initial icon position. The x and y values represent the position in the object's folder in percentage coordinates.TEMPLATE YES Creates object as a template. NO Resets objects template property.-----------------------------------------------------------------------------

*************************************WPProgram setup string parms*************************************KEYNAME VALUE Description-----------------------------------------------------------------------------<>EXENAME filename Sets the name of the programPARAMETERS params Sets the parameters list, which may include substitution charactersSTARTUPDIR pathname Sets the working directory- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<>PROGTYPE FULLSCREEN Sets the session type to OS/2 full screen PM Sets the session type to PM SEPARATEWIN Sets the session type to WIN-OS2 window running in a separate VDM. VDM Sets the session type to DOS full screen WIN Sets the session type to WIN-OS2 full screen WINDOWABLEVIO Sets the session type to OS/2 windowed WINDOWEDVDM Sets the session type to DOS windowed WINDOWEDWIN Sets the session type to WIN-OS2 windowedMINIMIZED YES Start program minimizedMAXIMIZED YES Start program maximizedNOAUTOCLOSE YES Leaves the window open upon program termination. NO Closes the window when the program terminates.-DOS Settings-NOTES:- To change these values you use SET keyname= Example: SET DOS_FILES=45;SET DOS_HIGH=1 Also for some use values of 1 for ON, 0 for off Example: SET COM_HOLD=1; (on, default is off) To add more than one DOS_DEVICE you need to separate with hex 0A (line-feed) Rexx example: h0A='0A'X setup='...;SET DOS_DEVICE=C:\OS2\MDOS\ANSI.SYS'h0A'C:\OS2\MDOS\EGA.SYS...'

List of DOS Setting fieldsCOM_HOLDDOS_BACKGROUND_EXECUTIONDOS_BREAKDOS_DEVICEDOS_FCBSDOS_FCBS_KEEPDOS_FILESDOS_HIGHDOS_LASTDRIVEDOS_RMSIZEDOS_SHELLDOS_STARTUP_DRIVEDOS_UMBDOS_VERSIONDPMI_DOS_APIDPMI_MEMORY_LIMITDPMI_NETWORK_BUFF_SIZEDPMI_DOS_APIEMS_FRAME_LOCATIONEMS_HIGH_OS_MAP_REGIONEMS_LOW_OS_MAP_REGIONEMS_MEMORY_LIMITHW_NOSOUNDHW_ROM_TO_RAMHW_TIMERIDLE_SECONDSIDLE_SENSITIVITYKBD_ALTHOME_BYPASSKBD_BUFFER_EXTENDKBD_RATE_LOCKMEM_INCLUDE_REGIONSMEM_EXCLUDE_REGIONSMOUSE_EXCLUSIVE_ACCESSPRINT_TIMEOUTVIDEO_FASTPASTEVIDEO_MODE_RESTRICTIONVIDEO_ONDEMAND_MEMORYVIDEO_RETRACE_EMULATIONVIDEO_ROM_EMULATIONVIDEO_SWITCH_NOTIFICATIONVIDEO_WINDOW_REFRESHVIDEO_8514A_XGA_IOTRAPXMS_HANDLESXMS_MEMORY_LIMITXMS_MINIMUM_HMA- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<>ASSOCFILTER filters Sets the filename filter for files associated to this program. Multiple filters are separated by commas.ASSOCTYPE type Sets the type of files associated to this program. Multiple filters are separated by commas.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<>MINWIN HIDE Views of this object will hide when their minimize button is selected. VIEWER Views of this object will minimize to the minimized window viewer when their minimize button is selected. DESKTOP Views of this object will minimize to the Desktop when their minimize button is selected.VIEWBUTTON HIDE Views of this object will have a hide button as opposed to a minimize button. MINIMIZE Views of this object will have a minimize button as opposed to a hide button.CCVIEW YES New views of this object will be created every time the user selects open. NO Open views of this object will resurface when the user selects open.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<>ICONFILE filename This sets the object's icon.ICONRESOURCE id,module This sets the object's icon. 'id' is the identity of an icon resource in the 'module' dynamic link library (DLL).ICONPOS x,y This sets the object's initial icon position. The x and y values represent the position in the object's folder in percentage coordinates.TEMPLATE YES Creates object as a template. NO Resets objects template property.- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -<>OBJECTID This sets the object's identity. The object id will stay with the object even if it is moved or renamed. An object id is any unique string preceded with a ' with a '>'. This may also be a real name specified as a fully qualified path name.HELPPANEL id This sets the object's default help panel.HELPLIBRARY filename This sets the help library.OPEN SETTINGS Open settings view when object is created. DEFAULT Open default view when object is created.NODELETE YES Will not allow you to delete the object.NOCOPY YES Will not allow you to make a copy.NOMOVE YES Will not allow you to move the object to another folder, will create shadow on a move.NODRAG YES Will not allow you to drag the object.NOLINK YES Will not allow you to create a shadow link.NOSHADOW YES Will not allow you to create a shadow link.NORENAME YES Will not allow you to rename the object.NOPRINT YES Will not allow you to print it.NOTVISIBLE YES Will not display the object.-----------------------------------------------------------------------------

/* FLDSHAD.CMD: Sample code using REXXUTIL's SysCreateObject function *//* Builds a folder on the DeskTop places a program object in it then *//* places a shadow of the program object on the DeskTop. *//* Mike Lamb: MIKELAMB/KGNVMC *//* Load REXXUTIL */call rxfuncadd sysloadfuncs, rexxutil, sysloadfuncscall sysloadfuncs

/* Syntax help */Helper:call SysClsSay '';Say ''; Say 'REBUILD:'Say 'Routine to rebuild system installed objects listed in *.RC files.'Say 'Can be used as an alternative to using the MAKEINI command.'Say 'Your INI.RC file is used by MAKEINI.EXE during installation to'Say 'create your OS2.INI file.'Say '';Say 'Any attempt to rebuild an object first deletes any object that'Say 'is using that same . This can be useful if you want to'Say 'restore an object back to its original installed state. This can'Say 'also be bad since if you rebuild a folder it first deletes all'Say 'objects in it since that is its initial install state.'Say ''; Say 'Syntax:';Say '';Say 'REBUILD object [(filespec]'Say '';Say 'Valid objects A(ll), F(olders), P(rograms), O(ther)'Say 'Can also can use (filespec for name of *.RC file, default is \OS2\INI.RC'Exit

call SysClsSay '';Say 'Using REXXUTILs to demonstrate use of the ICONRESOURCE parameter.'Say 'A folder will be created and populated with various icons found'Say 'in some installed DLL files.'Say '';Say 'ICONRESOURCE is a SysCreateObject setup string parameter, has syntax:'Say '';Say ' ICONRESOURCE=id module Ex: ICONRESOURCE=3 PMWP;'Say ' id=number of the icon resource, module=filename of the DLL'Say ''; Say 'NOTE: Over 70 icons, program will run for a minute or two.'Say ' After program ends the WPS will continue to resolve objects, also'Say ' the building of the objects adds approx 100K to your OS2.INI.'Say '';Say 'Press Y to add the folder to Desktop and populate...';Say '';parse upper value SysGetKey('NOECHO') with keyIf key<>'Y' Then Exit

System Settings===============During our attempts at customizing the shell using REXXUTILs for newly createdworkstations we discovered many items can be controlled. Our first attempt wasto turn off the default setting for Workplace Shell Print Screen. We wanted itdisabled instead of enabled (saves our customers from accidentally printingthe workplace shell screen contents 🙂From there we learned other items could be changed: