The Windows NT and `95 Library

DESCRIPTION

Execute imbedded assembled code.

SYNTAX

int asm(byte[] buf[, int eax[, int ebx[, int ecx[, int edx[, int esi[,
int edi]]]]]])

COMMENT

Make a call to the routine that you have coded into buf. eax, ebx, ecx, and edx are optional; if some or all are supplied, then the eax, ebx, ecx, and edx will be set to these values when the code at buf is called. The code in buf will be executed with a far call to that address, and is responsible for returning via retf or other means. The ScriptEase calling code will restore ALL registers except ss, sp, eax, ebx, ecx, and edx

RETURN

Returns a long value for whatever is in EAX when buf returns.

DESCRIPTION

Call base procedure of ScriptEase-made or subclassed window.

SYNTAX

int BaseWindowFunction(int Handle, int Message, int Param1,
int Param2)

COMMENTS

This calls the base procedure of a window created with a WindowFunction in MakeWindow() or subclassed with SubclassWindow(). This function would normally be used within your ScriptEase window function to pass the window parameter to the base procedure before handling it in your own code. Remember that if your window function returns no value, ScriptEase will call the base procedure automatically. This is the preferred method.

Handle : Window handle for window receiving this message. This must be the window handle of a window created with MakeWindow() or subclassed with SubclassWindow().

Message : The message ID

Param1 : First parameter for this Message ID

Param2 : Second parameter for this Message ID

RETURN

Returns the value returned by the base window function. If Handle is not a window with a WindowFunction created with MakeWindow() or is not window subclassed with SubclassWindow() then returns 0.

SEE ALSO

BreakWindow(), DoWindows(), MakeWindow(), SubclassWindow()

DESCRIPTION

Destroy a window created with MakeWindow(), or remove SubClass.

SYNTAX

bool BreakWindow([int WindowHandle])

COMMENTS

WindowHandle is a handle of a window created with a previous call to MakeWindow(). It is not an error for WindowHandle to be no-longer-valid.

If WindowHandle is a window created with MakeWindow(), then this destroys the window, calling all appropriate Windows' internal DestroyWindow() functions. Child windows are always removed before the parent. Any child windows of WindowHandle (created by earlier calls to MakeWindow() with WindowHandle as the parent) will be automatically destroyed with BreakWindow() before WindowHandle is destroyed.

If WindowHandle is a window controlled by SubclassWindow() then this will remove the WindowFunction from the message function loop.

If WindowHandle is not supplied, then all windows created with MakeWindow() will be removed.

RETURN

Returns True if the window was destroyed or un-subclassed, else False. If WindowHandle is not specified then returns True if all windows created with MakeWindow() were destroyed, else False. If WindowHandle is specified and WindowHandle window does not exist, then returns True.

EXAMPLE

See DoWindows() for an example.

SEE ALSO

BaseWindowFunction(), DoWindows(), MakeWindow()

DESCRIPTION

Process window messages.

SYNTAX

bool DoWindows([bool Peek = False])

COMMENTS

This function processes windows messages for this application.

RETURN

If Peek is TRUE (default is FALSE) this function returns immediately, regardless of whether there were messages for this application or not. If Peek is not supplied or is False, then this function yields control to other applications until a message has been processed (subject to filtering by MessageFilter()) for this application or for any window SubClassed by this application.

NOTE

This function should not be called recursively. That is, you should not call DoWindows() while within a message function processed during a previous call to DoWindows().

RETURN

Returns TRUE if any of the windows created with MakeWindow() or subclassed with SubClassWindow() are still open (i.e., have not received WM_NCDESTROY), else returns FALSE if no windows are still valid.

EXAMPLE

The following sample script will display a standard Windows window. All messages sent to that window will be logged to the ScriptEase text window. When that window is closed, through any standard Windows closing method, then this program will terminate.

#define WS_OVERLAPPEDWINDOW

#define WS_VISIBLE

#define CW_USEDEFAULT

if ( MakeWindow(NULL,NULL,"WindowFunction",

"Display Windows' messages",

WS_OVERLAPPEDWINDOW | WS_VISIBLE,

CW_USEDEFAULT, CW_USEDEFAULT, CW_USEDEFAULT,

CW_USEDEFAULT, NULL,0) )

{

}

WindowFunction(hwnd,msg,parm1,parm2,counter)

{

}

SEE ALSO

BaseWindowFunction(), MakeWindow()

DESCRIPTION

Call a function in a Dynamic Link Library (DLL).

SYNTAX

int DynamicLink(string ModuleName, string ProcedureName,
int CallingConvention,...)

int DynamicLink(string ModuleName, int Ordinal,
int CallingConvention,...)

COMMENTS

There are three versions of DynamicLink(): one for OS/2, one for Windows 3.x, and one for Windows `95 or NT. These three versions differ slightly in the way they are called, so if you wish to use the function in a script that will be run on different platforms you must create an operating system filter with the preprocessor directives #if, #ifdef, #elif, #else, and #endif.

DynamicLink() is a flexible method for making calls to the operating system or to dynamic link libraries (DLLs). If an operating-system function is needed but is not provided explicitly, this call will provide it. If you know the proper conventions for the call, then you can wrap a ScriptEase routine around a call to DynamicLink, and the call becomes available.

ModuleName is the name of the dynamic link that the procedure is located in.

ProcedureName is the name of the procedure in the ModuleName dynamic link library, if this procedure can be referenced by name.

Ordinal is the ordinal number of this procedure in the ModuleName dynamic link library.

CallingConvention may be any of the following:

CDECL Push right parameter first; Caller pops parameters.

STDCALL Push right parameter first; Caller pops parameters.

PASCAL Push left parameter first; Caller pops parameters.

The final parameters will be passed to the dynamically-linked function. All values will be passed as 32-bit values. If a parameter is undefined when DynamicLink() is called, then it is assumed that that parameter will be a 32-bit value that will be filled in (i.e., the address of a 32-bit data element is passed to the function, and that function will set the value).

If any parameter is a structure then it must be a structure that defines the binary data types in memory to represent the following variable. Before calling the DLL function, the structure will be copied to a binary buffer as described in BLObPut() and fwrite(). After calling the DLL function the binary data will be converted back into the data structure according to the rules defined in BLObGet() and fread(). Data conversion will be performed according to the current BigEndianMode setting (see fread()).

RETURN

Any of these calls return the value returned by the dynamically-linked function. 32-bits are returned.

SEE ALSO

fread() for the definition of passing of structures.

EXAMPLE

This example displays a simple message box, and waits for user to press Enter:

#define MESSAGE_BOX_ORDINAL 391 #define MB_OK 0x0000

// Message box contains one push button: OK.

#define MB_TASKMODAL 0x2000

// Must respond to this message

DynamicLink("USER32",MESSAGE_BOX_ORDINAL,STDCALL,

NULL, "This is a simple message box",

"Title of box", MB_OK | MB_TASKMODAL);

This accomplishes the same thing:

#define MB_OK 0x0000

// Message box contains one push button: OK.

#define MB_TASKMODAL 0x2000

// Must respond to this message

DynamicLink("USER32","MessageBoxA",STDCALL,NULL,

"This is a simple message box",

"Title of box", MB_OK | MB_TASKMODAL);

DESCRIPTION

Write new environment variables settings into a file.

SYNTAX

bool ESet(string FileSpec)

COMMENTS

This is a function for altering environment variables in the calling routine, since ScriptEase for OS/2 is unable to alter caller environment variables directly due to the limits of OS/2. It creates a file, named FileSpec, and inserts as at least as many statements of the form "SET VAR=Value" as necessary so that if these commands are executed, the environment variables will be updated as ScriptEase has used them. Note that this operation is unnecessary if the SE_ESET environment variable is set. In this case, the call ESet(%SE_ESET%) is automatically generated as the last statement before a smooth exit of ScriptEase.

RETURN

TRUE if successful, else FALSE if unable to open and write to FileSpec.

EXAMPLE

This line could be executed at the command line to add the directory C:\UTL to the PATH environment variable:

C:> SEWIN32 strcat(PATH,";C:\\UTL");

ESet("TempSet.cmd");

& TempSet & del TempSet.cmd

The following example sets the command prompt to include the date using the SESET.CMD sample batch file (see the OS/2 Appendix in this manual):

C:> SEWIN32 "sprintf(PROMPT,'%.10s %s',ctime(time()),'$P$G');"

DESCRIPTION

Get instance for this session.

SYNTAX

int Instance()

RETURN

Returns instance for this ScriptEase session.

DESCRIPTION

Define and create a window.

SYNTAX

int MakeWindow(int Parent, struct Class OR string Class,
string WindowFunction, string Text, int Style,
int Column, int Row, int Width, int Height,
BLOb CreateParm[, var UtilityVar])

COMMENTS

Make a window for processing during later calls to DoWindows(). The WindowClass is registered if it is an unknown class, and the WindowFunction is called by Windows for every Windows message. This is a complex function and forms the basis for all that you generally see in a Windows program.

Parent is the window handle of the parent for this new window. It is NULL to make the Window not have a parent (the desktop is the parent).

Class identifies the behavior of this window. If Class is a string then it must be the name of a pre-existing Windows class, such as "edit" or "button". If class is a structure then the window behavior is taken from the fields you choose to set in the structure. Any structure members that you don't set or are undefined, get the default value as described below. If struct Class is undefined or is NULL then all structure elements get default values.

The member elements of struct Class are:

.style - Windows class style; default CS_HREDRAW | CS_VREDRAW

.icon - Icon to appear when window is minimized; default NULL for no bitmap icon

.curso r - Cursor to appear when over this window; default is LoadCursor(NULL,IDC_ARROW)

.background - Background color of this window; default is GetStockObject(WHITE_BRUSH)

WindowFunction is the name of a ScriptEase function that will be called every time Windows sends a message to this new window. If WindowFunction is NULL then no ScriptEase function is called and the Windows default functions will be called. Your defined WindowFunction should return an integer or return nothing, and must have this format:

int WindowFunction(Handle,Message,Param1,Param2,UtilityVar)

Handle : Window handle for window receiving this message

Message : The message ID

Param1 : First parameter for this Message ID

Param2 : Second parameter for this Message ID

UtilityVar - is any variable that you choose to make available to the WindowFunction. This may be any kind of variable, including a structure if you want to pass many values to the WindowFunction. WindowFunction may also alter UtilityVar. If this parameter is not supplied, then no such additional variables will be available to the WindowFunction().

If your function returns a value, then the default Windows function is not called. If your WindowFunction DOES NOT return a value, then the default Window function or the string Class default function is called. WindowFunction is always called before the default function, except when the String Class is used. When the String Class is used, WM_CREATE messages (and other messages sent during Windows' calls to the CreateWindow() function) are not received by your function.

Note that MultiTask is OFF when this function is called; no other window will get processor time until your routine is done.

Text is the window caption or text. This may be set to NULL.

Style is the window style, as defined by the WS_xxxx values in Windows.hmm.

Col and Row describe the upper-left corner for the window when it is created. Use CW_USEDEFAULT to let Windows choose the position.

Width and Height describe the window size. Use CW_USEDEFAULT to let Windows choose the position.

CreateParm is an integer or a BLOb to data to pass with the WM_CREATE message. It is usually NULL.

UtilityVar - If you wish to pass additional variables to the function that handles the subclassed (or created) window's messages, put them here.

MODIFY

Your WindowFunction() may modify UtilityVar.

RETURN

On success, returns WindowHandle of the created window. Returns NULL for failure.

EXAMPLE

See DoWindows() for an example.

SEE ALSO

DoWindows(), BaseWindowFunction()

DESCRIPTION

Restrict message handled by ScriptEase window functions.

SYNTAX

int[] MessageFilter(int WinHandle, int MessageID1[,
int MessageID2[, int MessageID3[,...]]])

int[] MessageFilter(int WinHandle, int[] MessageIDs)

int[] MessageFilter(int WinHandle) // remove all message filters

COMMENTS

This function restricts the messages handled by ScriptEase for a window created with MakeWindow() or subclassed with SubclassWindow(). When Windows sends lots of messages, but you're only interested in handling a few of them within ScriptEase code, you can increase performance by specifying only those messages you want to handle in MessageFilter(). Any messages that have not been specified to MessageFilter() will not be handle by your WindowFunction and might not cause DoWindows() to return immediately (if Peek==False). Initially, there are no message filters so all messages are processed by ScriptEase.

To remove all message filters, so that all messages are passed through to the ScriptEase handler, use the third form of MessageFilter().

WinHandle is handle for a windows created with MakeWindow() or subclassed with SubclassWindow().

MessageID1 , MessageID2 ,... are messages to be added to those being filtered.

MessageIDs is an array of messages to be added to those being filtered.

RETURN

Returns an array of messages begin filtered prior to taking this call. Returns NULL if no messages are in the filter (i.e., all messages are passed through to ScriptEase functions) or if WinHandle is not a handle from a MakeWindow() or SubclassWindow() window.

SEE ALSO

DoWindows(), BaseWindowFunction(), MakeWindow(), SubclassWindow()

DESCRIPTION

Get Windows' handle for the ScriptEase text screen.

SYNTAX

int ScreenHandle()

RETURN

Returns handle the for ScriptEase text window corresponding to stdout.

DESCRIPTION

Hook into Window function for any window.

SYNTAX

bool SubclassWindow(int WindowHandle,
string WindowFunction[, var UtilityVar])

COMMENTS

This function will hook the specified WindowFunction() into the message loop for this window such that your function is called before the window's default or previously-defined function.

This function may be used to subclass any Window that is not already being managed by a WindowFunction for this ScriptEase instance. If the windows was created with MakeWindow() or is already subclassed then this function will fail. Note that this function may be used (but only once) with the window handle returned by ScreenHandle(). If you want to subclass the main ScriptEase window, it is best to open another instance of ScriptEase and subclass that rather than to subclass the instance that is powering your script. (Although it is possible to subclass that window, if you try to do anything with it you'll most likely get caught up in an infinite loop and hang).

WindowHandle is the window handle of the existing window to subclass.

WindowFunction is the same as in the MakeWindow() function. See MakeWindow(). Note that, as in the MakeWindow()function, if this function returns a value, then the default or subclassed function is not called. If this function returns no value then call is passed on to the previous function.

Use BreakWindow() to undo the window subclassing, or remove WindowFunction from the message loop.

MODIFY

Your WindowFunction() may modify UtilityVar.

RETURN

Returns boolean False if WindowHandle is invalid, was created with MakeWindow(), or is already Subclassed with this function; else return boolean True

SEE ALSO

DoWindows(), BaseWindowFunction(), BreakWindow(), MakeWindow(), MessageFilter()

DESCRIPTION

Retrieve list of window handles.

SYNTAX

int[] WindowList([int WinHandle])

COMMENTS

This function returns a list of parent window handles if WinHandle is not supplied or if WinHandle is NULL, else it returns an array of all child windows of WinHandle.

RETURN

Returns NULL if no window handles, else returns array of handles.