OS/2 Library

DESCRIPTION

Execute imbedded assembled code.

SYNTAX

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

COMMENTS

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.

EXAMPLE

The following example uses 80x6 assembly code to rotate memory bits:

RotateByteRight(/*byte*/b,/*int*/count)

// return value of byte b rotate count byte

{

assert( 0 <= b && b <= 0xFF );

assert( 0 <= count && count <= 8 )

// assembly code for would look as follows:

// ror al, cl D2C8

// ret

C3 return asm(`\xD2\xC8\xC3',b,0,count,0);

}

DESCRIPTION

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

SYNTAX

int DynamicLink(string ModuleName,string ProcedureName,

int BitSize, int CallingConvention,...)

int DynamicLink(string ModuleName,int Ordinal,int BitSize,

int CallingConvention,...)

int DynamicLink(int CallGate,int BitSize,int CallingConvention,...)

COMMENTS

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 by ScriptEase, 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.

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.

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.

CallGate is the gate selector for a routine that is referenced through a call gate.

CallingConvention may be any of the following:

CDECL Push right parameter first; Caller pops parameters.

STDCALL Push right parameter first; Callee pops parameters.

PASCAL Push left parameter first; Callee pops parameters.

BitSize defines whether this is a 16-bit or a 32-bit call. It may be either one of the pre-defined values: BIT16 or BIT32.

COMMENTS

The final parameters will be passed to the dynamically-linked function. For 32-bit functions, all values will be passed as 32-bit values. For 16-bit functions, if the parameter is a blob or a byte-array or an undefined value, then it will be passed as a 16:16 segment:offset pointer, otherwise all numeric values will be passed as 16-bit values, so if 32-bits is needed it will have to be passed in parts, with the low word first and the high word second.

If a parameter is undefined when DynamicLink() is called, then it is assumed 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 function is a wrapper for the 32-bit DosBeep:

DosBeep(Frequency,Duration)

// Frequency in Hz, Duration in milliseconds

{

#define DOS32BEEP_ORD 286

rc = DynamicLink("doscalls",DOS32BEEP_ORD,BIT32,

CDECL,Frequency,Duration);

return(rc);

}

This next example is a wrapper for the 16-bit (old) version of the DosBeep call, which uses a call gate:

DosBeep(Frequency,Duration)

// Frequency in Hz, Duration in milliseconds

{

#define DOS16BEEP_GATE 0x1692

rc = DynamicLink(DOS16BEEP_GATE,BIT16,PASCAL,

Frequency,Duration);

return(rc & 0xFFFF);

}

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:> SEOS2 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:> SEOS2 "sprintf(PROMPT,'%.10s %s',ctime(time()),'$P$G');"

DESCRIPTION

Retrieve information about this ScriptEase process.

SYNTAX

struct Info()

COMMENTS

This function retrieves information about the current ScriptEase process. All of these values can be determined through calls to DynamicLink(), but it is convenient to keep them here.

RETURN

Returns structure with the following members:

. Process ID of this ScriptEase process

. Thread ID of the calling thread

. Session ID of the session ScriptEase is running in

. WinHandle Handle for Window ScriptEase is running in

. SwitchHandle Switch handle for Win Switch functions

. hab Handle Anchor Block for this thread for access to some PM Win functions

SEE ALSO

PMInfo(), ProcessList()

DESCRIPTION

Read byte from a hardware port.

SYNTAX

byte inport(int portid)

COMMENTS

Read a byte from hardware port: portid.

DESCRIPTION

Read word from a hardware port.

SYNTAX

int inportw(int portid)

COMMENTS

Read a word (16 bit) from hardware port: portid. Value read is unsigned (not negative).

DESCRIPTION

Write byte to a hardware port.

SYNTAX

void outport(int portid,byte value)

COMMENTS

Write byte value to hardware port portid.

DESCRIPTION

Write word to a hardware port.

SYNTAX

void outportw(int portid,int value)

COMMENTS

Write word (16 bit) value to hardware port portid.

DESCRIPTION

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

COMMENTS

See DynamicLink() in this chapter. PMDynamicLink() is the same as DynamicLink() except that PMDynamicLink() passes DLL calls through the SEOS2PM.exe gateway program. Some PM functions require that they be made from a PM program. SEOS2.exe is not a PM program but SEOS2PM.exe is, so SEOS2PM can make these calls for SEOS2.exe. Addresses and buffers are automatically transferred and shared between SEOS2.exe and SEOS2PM.exe, so in most cases your code does not need to concern itself with memory protection. The exception to this is if one of the arguments to PMDynamicLink() contains a pointer or will receive a pointer. In these cases you will need to put or get that data explicitly by using PMpeek() and PMpoke() instead of the usual peek() and poke() routines.

SEE ALSO

DynamicLink(), PMInfo(), PMpeek(), Pmpoke()

DESCRIPTION

Retrieve information about the SEOS2PM process.

COMMENTS

See Info() in this chapter. PMInfo() works just the same as Info() but retrieves the same information for the SEOS2PM.exe gateway function. PMDynamicLink() functions often will want these values instead of those from Info().

SEE ALSO

Info(), PMDynamicLink(), PMpeek(), PMpoke()

DESCRIPTION

Read data from memory location via SEOS2PM.exe

COMMENTS

See peek() in chapter 8. PMpeek() is the same as peek() but it will access memory that is given to SEOS2PM.exe or may only be accessible from a PM program.

SEE ALSO

BigEndianMode, peek(), PMDynamicLink()

DESCRIPTION

Write data to memory location via SEOS2PM.exe.

COMMENTS

See poke() in chapter 8. PMpoke() is the same as poke() but it will access memory that is given to SEOS2PM .exe or may only be accessible from a PM program.

SEE ALSO

BigEndianMode, poke(), PMDynamicLink()

DESCRIPTION

Get list of all running processes.

SYNTAX

struct[] ProcessList([bool IncludeThreadInfo])

COMMENTS

This function builds an array of structures containing data for every running process in the system. If IncludeThreadInfo is TRUE, then information is also added for each thread in each process. If IncludeThreadInfo is not supplied then FALSE is assumed, so only Process data is returned.

RETURN

Returns NULL if error in getting ThreadInfo else returns an array of structures containing the following structure elements:

. id ProcessID for this process

. parent ProcessID for the parent of this process

. name ProcessID for the parent of this process

. name String containing the full name of this process

. threads Array of structures describing each thread of this process; this structure element will not be returned unless IncludeThreadInfo is set to equal TRUE, in which case .threads is an array of structures for each thread in the process, where the thread structure contains these structure elements:

. ProcID ID of this thread within the process

. SysID ID of this thread within the system

. Priority Running priority of this thread

. Status Current running state of this thread

SEE ALSO

Info(), PMInfo()