REXX Syscreateobject tips and techniques

From OS2World.Com Wiki
Jump to navigation Jump to search

This file contains 4 pieces of information:

  1. Large block of text containing information that pertains to the subject.(TEXT INFORMATION)
  2. Sample Rexx code to create a folder and program objects in the folder (FOLDER.CMD)
  3. Sample Rexx code to create shadows of objects. (SHADOW.CMD)
  4. Sample Rexx code to create a folder, then program object in the folder, then place a shadow of the program object on the desktop. (FLDSHAD.CMD)


Using the REXXUTIL SysCreateObject function

Using V2's REXXUTIL 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.

Michael Lamb MIKELAMB(KGNVMC)
Workstation Technical Support
Kingston NY

Help information regarding the SysCreateObject function of REXXUTIL

Function
SysCreateObject
Syntax
result = SysCreateObject(classname, title, location <,setup>)
classname
The name of the object class.
title
The object title.
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.
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.
Interesting INI information

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.

SysCreateObject / WinCreateObject

The various fields of the SysCreateObject call map closely with the WinCreateObject call.

 /***************************************************************************/
 /* This WinCreateObject function creates an instance of object class       */
 /* pszClassName, with title pszTitle, and places the icon and title in the */
 /* location referred to by pszLocation.                                    */
 /***************************************************************************/
 #define INCL_WINWORKPLACE
 #include <os2.h>
 
 PSZ      pszClassName;
 PSZ      pszTitle;
 PSZ      pszSetupString;
 PSZ      pszLocation;       /* Folder location */
 ULONG    ulFlags;           /* Creation flags */
 HOBJECT  Success;           /* Success indicator */
 
 Success = WinCreateObject(pszClassName,
             pszTitle, pszSetupString,
             pszLocation, ulFlags);

Putting it all together

The SysCreateObject parameters are now explained in more detail. (As I understand them...)

Remember Syntax: result = SysCreateObject(classname, title, location <,setup>)

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.
location
You can see above what the online Help information has in regards to this field. However by looking at the INI.RC file one can see a use of other "locations", such as <WP_DESKTOP>. 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 <WP_START>, make it a shadow of the object.
        <WP_DESKTOP>   The Desktop.
        <WP_START>     The Startup folder.
        <WP_OS2SYS>    The System folder.
        <WP_TEMPS>     The Templates folder.
        <WP_CONFIG>    The System Setup folder.
        <WP_INFO>      The Information folder.
        <WP_DRIVES>    The Drives folder.
        <WP_NOWHERE>   The hidden folder.

setup
This field needs the most explaining, and required the most "snooping". 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.
ALL parameters have safe defaults, so it is never necessary to pass unnecessary parameters to an object.
Below are both WPFolder and WPProgram setup string parameters. Their various key names, values and a short description follow each item. The <<xxx>> item is there to give you an idea of what settings "page" you would find this information on.
 
*********************************
***WPFolder setup string parms***
*********************************
KEYNAME      VALUE           Description
-----------------------------------------------------------------------------
<<View>>
ICONVIEW     NONFLOWED       Set icon view to non-flowed
             FLOWED          Set icon view to flowed
             NOLINES         Set icon view to non-grid
<<File>>
WORKAREA     YES             Make the folder a Workarea folder
<<Window>>
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.
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.
CONCURRENTVIEW 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.
<<General>>
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
-----------------------------------------------------------------------------
<<Program>>
EXENAME      filename        Sets the name of the program
PARAMETERS   params          Sets the parameters list, which may
                             include substitution characters
STARTUPDIR   pathname        Sets the working directory
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<<Sessions>>
PROGTYPE     FULLSCREEN      Sets the session type to OS/2 full screen
             WINDOWABLEVIO   Sets the session type to OS/2 windowed
             VDM             Sets the session type to DOS full screen
             WINDOWEDVDM     Sets the session type to DOS windowed
             PM              Sets the session type to PM
             WIN             Sets the session type to WIN-OS2 Fullscreen
             WINDOWEDWIN     Sets the session type to WIN-OS2 windowed
             SEPARATEWIN     Sets the session type to WIN-OS2 windowed,
                             separate session.
MINIMIZED    YES             Start program minimized
MAXIMIZED    YES             Start program maximized
NOAUTOCLOSE  YES             Leaves the window open upon program termination.
             NO              Closes the window when the program terminates.
-DOS Settings-
(To change these values you use SET keyname=)
(Example:   SET DOS_FILES=45;
(Also for some use values of 1 for ON, 0 for off)
(Example:   SET COM_HOLD=1;     (on, default is off)
List of DOS Setting fields
COM_HOLD
DOS_BACKGROUND_EXECUTION
DOS_BREAK
DOS_DEVICE
DOS_FCBS
DOS_FCBS_KEEP
DOS_FILES
DOS_HIGH
DOS_LASTDRIVE
DOS_RMSIZE
DOS_SHELL
DOS_STARTUP_DRIVE
DOS_UMB
DOS_VERSION
DPMI_DOS_API
DPMI_MEMORY_LIMIT
DPMI_NETWORK_BUFF_SIZE
DPMI_DOS_API
EMS_FRAME_LOCATION
EMS_HIGH_OS_MAP_REGION
EMS_LOW_OS_MAP_REGION
EMS_MEMORY_LIMIT
HW_NOSOUND
HW_ROM_TO_RAM
HW_TIMER
IDLE_SECONDS
IDLE_SENSITIVITY
KBD_ALTHOME_BYPASS
KBD_BUFFER_EXTEND
KBD_RATE_LOCK
MEM_INCLUDE_REGIONS
MEM_EXCLUDE_REGIONS
MOUSE_EXCLUSIVE_ACCESS
PRINT_TIMEOUT
VIDEO_FASTPASTE
VIDEO_MODE_RESTRICTION
VIDEO_ONDEMAND_MEMORY
VIDEO_RETRACE_EMULATION
VIDEO_ROM_EMULATION
VIDEO_SWITCH_NOTIFICATION
VIDEO_WINDOW_REFRESH
VIDEO_8514A_XGA_IOTRAP
XMS_HANDLES
XMS_MEMORY_LIMIT
XMS_MINIMUM_HMA
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<<Association>>
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.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<<Window>>
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.
CONCURRENTVIEW 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.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<<General>>
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.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
<<Misc>>
OBJECTID     <name>          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 '<' and terminated
                             with a '>'.
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.
-----------------------------------------------------------------------------
IMPORTANT NOTE
Always make sure your setup string ends with a semi-colon!


Good Luck....

REXX CMD SAMPLES

FOLDER.CMD

/* FOLDER.CMD: Sample code using REXXUTIL's SysCreateObject function */ /* Builds a folder on the DeskTop and places some program objects in it.*/

/* Mike Lamb: MIKELAMB/KGNVMC */

/* Load REXXUTIL */ call rxfuncadd sysloadfuncs, rexxutil, sysloadfuncs call sysloadfuncs

/* The basic call is listed next. */ /* result = SysCreateObject(classname, title, location, setup) */

call SysCls Say ;Say 'Using REXXUTILs to Add a Folder and Program Objects...'

Say ;Say 'Press Y to add Test Folder to Desktop...';Say ; parse upper value SysGetKey('NOECHO') with key If key<>'Y' Then Exit

/* All of the routines pass parameters to a subroutine to perform the call */ classname='WPFolder' title='Test Folder' location='<WP_DESKTOP>' setup='OBJECTID=<TEST_FOLDER>;' Call BldObj

Say ;Say 'Now go and open up the folder, currently no items are there.' Say 'Press ENTER and we will add a few program objects...' key=SysGetKey()

Say 'Place a program object into the folder...';Say ; classname='WPProgram' title='SYSLEVEL-FULLSCR' location='<TEST_FOLDER>' setup='PROGTYPE=FULLSCREEN;EXENAME=\OS2\SYSLEVEL.EXE;OBJECTID=<TEST_SYSL>;' Call BldObj

classname='WPProgram' title='CHKDSK-PM' location='<TEST_FOLDER>' setup='MINIMIZED=YES;PROGTYPE=PM;EXENAME=\OS2\PMCHKDSK.EXE;OBJECTID=<TEST_PMCK>;' Call BldObj

classname='WPProgram' title='SYSLEVEL-VIO' location='<TEST_FOLDER>' setup='PROGTYPE=WINDOWABLEVIO;EXENAME=\OS2\SYSLEVEL.EXE;OBJECTID=<TEST_SYSLVIO>;' Call BldObj

classname='WPProgram' title='MEM-Fullscreen' location='<TEST_FOLDER>' setup='PROGTYPE=VDM;EXENAME=\OS2\MDOS\MEM.EXE;PARAMETERS=/?;NOAUTOCLOSE=YES;OBJECTID=<TEST_MEMFUL>;' Call BldObj

classname='WPProgram' title='MEM-WindowVDM' location='<TEST_FOLDER>' setup='PROGTYPE=WINDOWEDVDM;EXENAME=\OS2\MDOS\MEM.EXE;PARAMETERS=/?;NOAUTOCLOSE=YES;OBJECTID=<TEST_MEMWIN>;' Call BldObj

Say ;Say 'All done, to remove objects drag to shredder...'

Exit

/* Build Object */ BldObj: call charout ,'Building: 'title

result = SysCreateObject(classname, title, location, setup)

If result=1 Then call charout ,'... Object created!' Else call charout ,'... Not created! Return code='result

Say ; Return

SHADOW.CMD

/* SHADOW.CMD: Sample code using REXXUTIL's SysCreateObject function    */
/* Builds shadows on the DeskTop and Startup Folder                     */
 
/* Mike Lamb: MIKELAMB/KGNVMC                                           */
 
call rxfuncadd sysloadfuncs, rexxutil, sysloadfuncs
call sysloadfuncs
 
Call SysCls
Say '';Say 'Using REXXUTILs to Add Shadow Objects...'
 
/* The titles and objectid's are found from the \OS2\INI.RC file */
 
Say '';Say 'First lets place some items on the Desktop...'
title='Enhanced Editor'; objid='<WP_EPM>'   ; loc='<WP_DESKTOP>'; call AddShad
title='OS/2 Window'    ; objid='<WP_OS2WIN>'; loc='<WP_DESKTOP>'; call AddShad
title='System Clock'   ; objid='<WP_CLOCK>' ; loc='<WP_DESKTOP>'; call AddShad
 
Say '';Say 'Now lets place an item in the Startup Folder...'
title='System Clock'   ; objid='<WP_CLOCK>' ; loc='<WP_START>'  ; call AddShad
 
Say '';Say 'All done, to remove objects drag to shredder...'
 
Exit
 
AddShad:
Say '';Say 'Press Y to add shadow object: 'title' to 'loc
parse upper value SysGetKey('NOECHO') with key

If key='Y' Then Do
 
   result=SysCreateObject('WPShadow', title, loc, 'SHADOWID='objid)
 
   If result=1 Then Say 'Object created'
   Else             Say 'Not created, return code='result
End
Return

FLDSHAD.CMD

/* 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, sysloadfuncs
call sysloadfuncs
 
/* The basic call is listed next.                                          */
/* result = SysCreateObject(classname, title, location, setup)             */
 
call SysCls
Say '';Say 'Using REXXUTILs to Add Folder/Program/Shadow Objects...'
 
Say '';Say 'Press Y to add Test Folder to Desktop...';Say '';
parse upper value SysGetKey('NOECHO') with key
If key<>'Y' Then Exit
 
classname='WPFolder'
title='Test Folder'
location='<WP_DESKTOP>'
setup='OBJECTID=<TEST2_FOLDER>;'
Call BldObj
 
Say '';Say 'Press Y to place a program object into the folder...';Say '';
parse upper value SysGetKey('NOECHO') with key
If key<>'Y' Then Exit
 
classname='WPProgram'
title='SYSLEVEL-VIO'
location='<TEST2_FOLDER>'
setup='PROGTYPE=WINDOWABLEVIO;EXENAME=\OS2\SYSLEVEL.EXE;OBJECTID=<TEST2_SYSLVIO>;'
Call BldObj
 
Say '';Say 'Press Y to place a shadow of the program object on the Desktop...';Say '';
parse upper value SysGetKey('NOECHO') with key
If key<>'Y' Then Exit
 
classname='WPShadow'
title='SYSLEVEL-VIO'
location='<WP_DESKTOP>'
setup='SHADOWID=<TEST2_SYSLVIO>;'
Call BldObj
 
Say '';Say 'All done, to remove objects drag to shredder...'
 
Exit
 
/* Build Object */
BldObj:
call charout ,'Building: 'title
 
result = SysCreateObject(classname, title, location, setup)
 
If result=1 Then call charout ,'...   Object created!'
Else             call charout ,'...   Not created! Return code='result
 
Say '';
Return