home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Power-Programmierung
/
CD1.mdf
/
rexx
/
library2
/
rexhlapi
/
rexhlapi.inf
(
.txt
)
< prev
next >
Wrap
OS/2 Help File
|
1991-03-20
|
49KB
|
2,289 lines
ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ
OS/2 REXHLAPI Dynamic Link Library Reference
Version 1.00
(c) Copyright W. David Ashley 1991. All rights reserved.
Program and Documentation by
W. David Ashley
No warranties, guarantees, etc. are implied, and no liability is assumed for
the code, examples, DLLs, or documentation.
This software is user-supported software and may be freely copied and used by
anyone who wishes to do so as long as the following conditions are met:
1. These functions may not be used by any program for which a fee is charged
unless the owner of the program has paid the registration fee.
2. If you transmit a copy of this software to another party you must give
them the complete unaltered contents of the REXHLAPI.ZIP file.
3. If you make any modifications to these functions you must change the name
of the dynamic link library file REXHLAPI.DLL to some other name.
If you feel that this program has benefited you, please register it by sending
$25.00 to:
W. David Ashley
5 Timberline Dr.
Trophy Club, Tx 76262
The source code for REXHLAPI can be obtained by sending $75.00 ($25.00
registration + $50.00 source code) to the same address.
If you have questions, comments or suggestions please contact me through the
OS/2 Shareware BBS or at the address above.
DESCRIPTION
This document is intended for application developers who wish to use EHLLAPI
services from OS/2 REXX cmds. The EHLLAPI services are available in REXX as an
external function package, and are loaded only when used.
A general understanding of the available EHLLAPI services to Communications
Manager by the reader is assumed by the author. For more information on the
specific services available in EHLLAPI refer to the IBM Operating System/2
Extended Edition Version 1.2 EHLLAPI Programming Reference manual.
BEFORE YOU BEGIN
Before you begin to use this reference, it would be helpful to understand how
you can:
o Expand the Contents window to see all available topics
o Obtain additional information for a highlighted word or phrase
o Use action bar choices.
HOW TO USE THE CONTENTS
When the Contents window is first displayed, some topics have a plus (+) sign
beside them. The plus sign indicates that additional topics are available.
To expand the Contents window if you are using a mouse, click on the plus
sign. If you are using the keyboard, use the Up Arrow () or Down Arrow ()
key to highlight the topic and press the Plus (+) key. For example,
Introduction has a plus sign beside it. To see the complete list of topics,
click on the plus sign or highlight that topic and press the Plus key.
To view a topic, double-click on the topic (or press the Up Arrow or Down
Arrow key to highlight the topic and then press the Enter key).
HOW TO OBTAIN ADDITIONAL INFORMATION
After you select a topic, the information for that topic is displayed in a
window. Highlighted words or phrases indicate that additional information is
available. You will notice that certain words in the following section are
highlighted. If you are using a mouse, double-click on the highlighted word.
If you are using a keyboard, press the Tab key to move to the highlighted word
and then press the Enter key. Additional information will be displayed in a
pop-up window.
HOW TO USE ACTION BAR CHOICES
A number of choices are available for managing information presented in the
OS/2 LAN Command Reference. If you want to see more information about these
choices, double-click on the name of the choice (or press the Tab key to move
to the choice and press the Enter key).
Bookmark Allows you to set a placeholder so you can retrieve information of
interest to you. (This choice is available from the Services
pull-down.)
Search Allows you to find occurrences of a word or phrase in the current
topic, selected topics, or all topics. (This choice is available
from the Services pull-down.)
Print Allows you to print one or more topics. (This choice is available
from the Services pull-down.)
Copy Allows you to copy a topic you are viewing to a file you can edit.
(This choice is available from the Services pull-down.)
Options Allows you to change the way your Contents window is displayed.
TRADEMARKS
The following trademarks apply to this reference:
o IBM is a registered trademark of International Business Machines
Corporation.
o Operating System/2 and OS/2 are trademarks of International Business
Machines Corporation.
o Personal System/2 and PS/2 are trademarks of International Business Machines
Corporation.
o REXX/2 is a trademark of International Business Machines Corporation.
ΓòÉΓòÉΓòÉ 1.1. Requirements ΓòÉΓòÉΓòÉ
REXHALPI requires the following environment
o OS.2 1.2 Extended Edition or later
ΓòÉΓòÉΓòÉ 1.2. Installation ΓòÉΓòÉΓòÉ
Copy REXHLAPI.DLL to a directory specified in your LIBPATH.
Note: If you have a previous copy of REXHLAPI loaded and OS/2 cannot
open/replace the file then a copy of the DLL currently resides in memory.
Reboot and before executing any REXX cmds that reference REXHLAPI copy the file
to your LIBPATH destination.
ΓòÉΓòÉΓòÉ 1.3. Usage ΓòÉΓòÉΓòÉ
Add the following lines to all application cmds to insure the function is
registered.
if RxFuncQuery('rexhllapi') then ,
call RxFuncAdd 'rexhllapi', 'rexhlapi', 'rexhllapi'
The above example would add the REXHLLAPI function so that it can be used. The
first argument specifies how you wish to refer to the function in your program
(its name in the program). The second argument references the name of the
REXHLAPI.DLL library (always 'REXHLAPI'). And the third argument references the
name of the entry point in the library which contains the code for the function
referenced in the first argument (always 'REXHLLAPI').
To drop the function when the application is done execute the following.
call RxFuncDrop 'rexhllapi'
The function name now becomes unknown to the interpreter and will generate a
runtime error if used after this point in the program.
Refer to IBM Operating System/2 Procedures Language 2/REXX Reference manual for
more information on the RxFuncAdd and RxFuncDrop statements.
Note: The case of the strings passed to RxFuncAdd and RxFuncDrop is not
important. The string will be converted to all upper case by the REXX
interpreter automatically.
ΓòÉΓòÉΓòÉ 2. How to Read the Syntax Diagrams ΓòÉΓòÉΓòÉ
The syntax diagram shows you how to specify a function so that REXX/2 can
correctly interpret what you type. Read the syntax diagram from left to right
and from top to bottom, starting at the ΓöÇ symbol, following the horizontal
line (the main path). A line ending with an ΓöÇ means that the command syntax is
continued. A line starting with an ΓöÇ means that the syntax is continued from
the previous line. The ΓöÇ symbol marks the end of the function syntax.
Required parameters are displayed on the main path; optional parameters are
displayed below it.
Parameters are classified as constants or variables. String constants must be
delimited by the standard REXX/2 quotation marks. A function name is a keyword.
REXX/2 functions may be either CALLed or referenced as a function entry. Some
of the external functions presented here do not return any values.
Variables appear in lowercase letters and represet names or values you supply.
Include all punctuation shown in the diagram, such as colons, semicolons,
commas, quotation marks, and equal signs.
Example:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Change_Window_Name', nameparmΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
ΓòÉΓòÉΓòÉ 3. Functions Overview ΓòÉΓòÉΓòÉ
The EHLLAPI function package provides a single function name to be used with a
set of parameters.
The general format of the EHLLAPI function invocation is:
retval = REXHLLAPI(function-string [, parameters]);
or
call REXHLLAPI function-string [, parameters];
The function-string determines the EHLLAPI function to be invoked. The case of
the function-string is not significant but the case of all parameters are used
by the function package as they are passed to it. The number of parameters is
dependent on the EHLLAPI function to be invoked.
Generally the data returned by a function is the return code generated by the
coresponding EHLLAPI function of the same name or a data string returned by the
specified function. In all cases if the function package determines an error in
the number of parameters or some other general error then the specified
function is not performed and the null string ('') is returned.
In addition, the REXX variable HLLAPIRETC is also set by the REXHLAPI function
package. The combination of the returned data string and the contents of the
REXX variable HLLAPIRETC provide a clear mechanism in determining the results
of the execution of any of the EHLLAPI functions. The following outlines all
the possible combinations and their meaning:
o If both the returned data and the HLLAPIRETC variable are the null string
('') then there was an error detected in the number of input argument(s) to
the function or their contents.
o If the HLLAPIRETC is the null string and the returned data is not the null
string then the returned data should be ignored because the specified
EHLLAPI function was not performed. The only exception to this rule is the
Get_RexHLLAPI_Ver service because it does not execute an EHLLAPI function.
o If the returned data is not the null string and it is equal to the
HLLAPIRETC variable then the specified EHLLAPI function was executed and the
return code from that function has been returned in the returned data.
o In all other cases the specified EHLLAPI function will have been executed
and data from that function is returned. The return code from the function
will be set in the HLLAPIRETC variable.
The function-strings, parameters and returned data follow in alphabetical
order.
ΓòÉΓòÉΓòÉ 3.1. Change_Window_Name (Service 106) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Change_Window_Name', nameparmΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Changes the presentation space window name to the specified new name. The old
name is saved by the system and is restored on a call to the Disconnect_PS
service or changed on a subsequent call to the Change_Window_Name service.
Prerequisite Calls:
Connect_Window_Srvcs service
Arguments:
argument 1 The string constant or a variable whose contents are
'Change_Window_Name'.
nameparm A string of the form:
o 1 byte short session name
o 1 byte change option
- A x'01' for changing the presentation space name
- A x'02' for resetting the presentation space name
o 1-60 bytes containing the new presentation space name. If byte 2 is x'02'
then this field is optional. The maximum length of the new name is 60
characters.
Returns:
The return code from the Change_Window_Name EHLLAPI service is returned.
'0' Ok
'1' Byte 1 of nameparm is invalid
'2' nameparm error
'9' System error
'11' Session is stopped
Example:
Change the 'A' session window name to "My Program".
call REXHLLAPI 'Connect_PM_Srvcs', 'A'
call REXHLLAPI 'Change_Window_Name', 'A' || c2x('01') || 'My Program'
call REXHLLAPI 'Disconnect_PM_Srvcs', 'A'
ΓòÉΓòÉΓòÉ 3.2. Change_Switch_Name (Service 105) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Change_Switch_Name', nameparmΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Changes the presentation space switchlist name to the specified new name. The
old name is saved by the system and is restored on a call to the Disconnect_PS
service or changed on a subsequent call to the Change_Switch_Name service.
Prerequisite Calls:
Connect_Window_Srvcs service
Arguments:
argument 1 The string constant or a variable whose contents are
'Change_Switch_Name'.
nameparm A string of maximum length layed out as follows:
o 1 byte short session name
o 1 byte change option
- A x'01' for changing the switch list name of the PS
- A x'02' for resetting the switch list name of the PS
o 1-60 bytes containing the new switch list name. If byte 2 is x'02' then
this field is optional. The maximum length of the new name is 60
characters.
Returns:
The return code from the Change_Switch_Name EHLLAPI service is returned.
'0' Ok
'1' Byte 1 of nameparm is invalid
'2' nameparm error
'9' System error
'11' Session is stopped
Example:
Change the 'A' session switch list name to "My Program".
call REXHLLAPI 'Connect_PM_Srvcs', 'A'
call REXHLLAPI 'Change_Switch_Name', 'A' || c2x('01') || 'My Program'
call REXHLLAPI 'Disconnect_PM_Srvcs', 'A'
ΓòÉΓòÉΓòÉ 3.3. Connect_PM_Srvcs (Service 101) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Connect_PM_Srvcs', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Connects the application to a presentation space for only the EHLLAPI
Presentation Manager services.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Connect_PM_Srvcs'.
session_id The short session name of the presentation space in which PM
services are to be performed.
Returns:
The return code from the Connect_PM_Srvcs EHLLAPI service is returned.
'0' Ok
'1' session_id was invalid
'9' System error
'10' Function not supported
'11' System resource unavailable. Presentation space already in use.
Example:
retc = REXHLLAPI('Connect_PM_Srvcs', 'A')
ΓòÉΓòÉΓòÉ 3.4. Connect_PS (Service 1) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Connect_PS', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Connects the program to a logical Communications Manager session specified by
the presentation space short name session_id. See the Communications Manager
Configuration services to determine the names of the sessions configured on
your system or use the service Query_sessions to obtain the session information
dynamically.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Connect_PS'.
session_id The short session name (1 character) of the session you wish to
be connected to. The case of this character is not important.
Returns:
The return code from the Connect_PS EHLLAPI service is returned.
'0' Connected ok
'1' Invalid session_id
'4' Connect, session busy
'5' Connect, session locked
'9' System error
'11' Session already connected to another application
Note: Other return codes are possible from this service.
Example:
retc = REXHLLAPI('Connect_PS', 'A')
ΓòÉΓòÉΓòÉ 3.5. Convert_Position (Service 99) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇrow = RexHLLAPI('Convert_Position', session_id, position)ΓöÇΓöÇΓöÇ
Purpose:
Converts position to row/column.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Convert_Position'.
session_id The short session name (1 character) identifying the session
from which the conversion info is to be taken.
position The position to be converted to row/column format. Valid
argument values for a 24 by 80 presentation space would be 1 to
1920.
Returns:
The return code from the Convert_Position EHLLAPI service is returned.
'0' Position specified is outside the presentation space
> '0' < '9998' The row number of the converted position
= '9998' Invalid session_id
= '9998' REXHLAPI internal error. Contact author.
Note: If this function returns a value > '0' < '9998' then the REXX variable
HLLAPIRETC contains the column number of the converted position.
Example:
The following example
row = REXHLLAPI('convert_pos', 'a', 170);
/* Now ROW = '3' and HLLAPIRETC = '10' */
would return '3' and set HLLAPIRETC = '10' in a 24 by 80 presentation space.
ΓòÉΓòÉΓòÉ 3.6. Convert_RowCol (Service 99) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpos = RexHLLAPI('Convert_RowCol', session_id, column, row)ΓöÇΓöÇ
Purpose:
Converts row/column info in the session session_id, to presentation space
position.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Convert_RowCol'.
session_id The short session name (1 character) identifying the session
from which the conversion info is to be taken.
col The column component to be converted. Valid argument values for
a 24 by 80 presentation space would be 1 to 80.
row The row component to be converted. Valid argument values for a
24 by 80 presentation space would be 1 to 24.
Returns:
The return code from the Convert_RowCol EHLLAPI service is returned.
'0' Row or column specified is outside presentation space
> '0' < '9998' The position (upper left is position 1)
= '9998' Invalid session_id
= '9998' REXHLAPI internal error. Contact author.
Example:
The following example
pos = REXHLLAPI('convert_rowcol', 'a', 10, 3);
would return '170' in a 24 by 80 presentation space.
ΓòÉΓòÉΓòÉ 3.7. Copy_Field_To_Str (Service 34) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇfielddata = RexHLLAPI('Copy_Field_To_Str', pos, length)ΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Copies the field data located at pos in the connected presentation space, for
length length. The pos and length values can be found by using the
Find_field_pos and Find_field_len services described elsewhere in this manual.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Copy_field_to_str'.
pos The position of the field to be copied.
length The number of character to be copied.
Returns:
The requested field data string is returned.
'' No field data at pos, or invalid pos. Check the value of the REXX
variable HLLAPIRETC.
fielddata The data of length length or up to the end of the field at pos.
Example:
The following example
fielddata = REXHLLAPI('copy_field_to_str', 26, 10);
would copy 10 characters at position 26 from the currently presentation space.
ΓòÉΓòÉΓòÉ 3.8. Copy_Oia (Service 13) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇoiadata = RexHLLAPI('Copy_Oia')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the Operator Information Area from the connected session. Refer to the
IBM Operating System/2 Extended Edition Version 1.2 EHLLAPI Programming
Reference manual for more information on the contents of the Oia data.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Copy_Oia'.
Returns:
The Operator Information Area data string is returned.
'' Not connected or other error. Check the value of the REXX variable
HLLAPIRETC.
oiadata A 103 byte copy of the OIA data consisting of
o A 1 byte format field set to '1'
o An 80 byte data field with the contents of the OIA line
o A 22 byte OIA group field
ΓòÉΓòÉΓòÉ 3.9. Copy_PS (Service 5) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpsdata = RexHLLAPI('Copy_PS')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Return the entire contents of the currently connected session or '' (null
string) if not connected to a session. The contents of the returned data is
dependant on the setting of the EAB (Extended Attribute Bytes) value in the
Set_session_parms service described elsewhere. Briefly, if EAB is OFF then only
the TEXT of the presentation space will be returned. If EAB is ON then 2 bytes
will be returned for each displayable byte on the screen. The first will
contain the EAB value, the second will contain the text data.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are 'Copy_PS'.
Returns:
The entire contents of the currently connected presentation space are returned
as a single string.
'' Not connected or other error. Check the value of the REXX variable
HLLAPIRETC.
psdata 1920 bytes of data if the presentation space is 24 x 80 and the EAB
is OFF, 3840 bytes if the EAB is ON.
ΓòÉΓòÉΓòÉ 3.10. Copy_PS_To_Str (Service 8) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpsdata = RexHLLAPI('Copy_PS_To_Str', pos, length)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns data from the curently connected session from position pos for length
length, or '' if not connect or an error. See the discussion of EAB setting in
the Copy_PS service elsewhere.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Copy_PS_to_str'.
Returns:
The specified portion of the currently connected presentation space is
returned as a string.
'' Not connected or other error. Check the value of the REXX variable
HLLAPIRETC.
psdata length characters of data if the EAB is OFF or length x 2 if the EAB
is ON.
Example:
The following example
psdata = REXHLLAPI('copy_ps_to_str', 26, 10);
would copy 10 characters at position 26 from the currently presentation space.
ΓòÉΓòÉΓòÉ 3.11. Copy_Str_to_Field (Service 33) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Copy_str_to_field', string, posΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Copies string to the field at pos position in the connected session.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Copy_str_to_field'.
string Data string to be copied.
pos Position of the destination field in the presentation space.
Returns:
The return code from the Copy_str_to_field EHLLAPI service is returned.
'0' Ok
'1' Target not allowed
'2' Zero length string
'5' Protected field or bad string data (bad attribute)
'6' Data copied, but truncated because string was longer than the field.
'7' pos is invalid
'24' The screen has no fields (unformatted)
Example:
The following example
call REXHLLAPI 'copy_str_to_field', 'logoff', 90
would copy the string 'logoff' to the currently presentation space field at
postion 90.
ΓòÉΓòÉΓòÉ 3.12. Copy_Str_to_PS (Service 15) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Copy_str_to_PS', string, posΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Copies string to pos position in the connected session.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Copy_str_to_PS'.
string Data string to be copied.
pos Position of the destination in the presebtation space.
Returns:
The return code from the Copy_str_to_PS EHLLAPI service is returned.
'0' Ok
'1' Target not allowed
'2' Zero length string
'5' Protected field or bad string data (bad attribute)
'6' Data copied, but truncated because string was longer than the field.
'7' pos is invalid
Example:
The following example
call REXHLLAPI 'copy_str_to_ps', 'logoff', 90
would copy the string 'logoff' to the currently presentation space at position
90.
ΓòÉΓòÉΓòÉ 3.13. Disconnect_PM_Srvcs (Service 102) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Disconnect_PM_Srvcs', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Disconnects the Presentation Manager window services connection.
Prerequisite Calls:
Connect_Window_Srvcs service
Arguments:
argument 1 The string constant or a variable whose contents are
'Disconnect_PM_Srvcs'.
Session_id The short session presentation space name from which to
disconnect.
Returns:
The return code from the Disconnect_PM_Srvcs EHLLAPI service is returned.
'0' Ok
'1' Not connected
'9' System error
Example:
call REXHLLAPI 'Disconnect_PM_Srvcs', 'A'
ΓòÉΓòÉΓòÉ 3.14. Disconnect_PS (Service 2) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Disconnect_PS'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Disconnects from the currently connected presentation space session.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Disconnect_PS'.
Returns:
The return code from the Disconnect_PS EHLLAPI service is returned.
'0' Ok
'1' Not connected
Example:
call REXHLLAPI 'Disconnect_PS'
ΓòÉΓòÉΓòÉ 3.15. Find_Field_Len (Service 32) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Find_Field_Len', search_option, posΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the length of the field with attributes search_option starting at
position pos within the current field or '0' if the specified field type could
not be found.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Find_Field_Len'.
search_option The values for search_option are:
' ' or 'T ' The current field (the field that the cursor is in)
'P ' Previous field, either protected or unprotected.
'NP' Next protected field
'NU' Next unprotected field
'PP' Previous protected field
'PU' Previous unprotected field
pos The starting position in the presentation space from which
the search is to begin.
Returns:
The length of the found specified field type is returned.
'0' The specified field type could not be located
> '0' The length of the found specified field type
ΓòÉΓòÉΓòÉ 3.16. Find_Field_Pos (Service 31) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Find_Field_Pos', search_option, posΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the position of the field with attributes search_option starting at
position pos within the presentation space or '0' if the specified field type
could not be found.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Find_Field_Pos'.
search_option The values for search_option are:
' ' or 'T ' The current field (the field that the cursor is in)
'P ' Previous field, either protected or unprotected.
'NP' Next protected field
'NU' Next unprotected field
'PP' Previous protected field
'PU' Previous unprotected field
pos The starting position in the presentation space from which
the search is to begin.
Returns:
The position of the found specified field type is returned.
'0' The specified field type could not be located
> '0' The position of the found specified field type
ΓòÉΓòÉΓòÉ 3.17. Get_key (Service 51) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇkeyval = RexHLLAPI('Get_key', session_id)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Return the next intercepted keystroke from the session specified. The service
Start_Keystroke_Intercept enables the application to intercept keystrokes from
the user.
For more information on the returned data from this function refer to the IBM
operating System/2 Extended Edition Version 1.2 EHLLAPI Programming Reference
manual.
Prerequisite Calls:
Start_Key_Intercept service
Arguments:
argument 1 The string constant or a variable whose contents are 'Get_Key'.
session_id The short session name of the presentation space from which to
obtain the keystroke.
Returns:
The intercepted keystroke data string is returned.
'' If an error, or not connected to session_id. Check the value of the
REXX variable HLLAPIRETC.
keyval If no error, the contents of string depend on the keys pressed by
the 3270 session operator, for example:
Byte 1 The session_id
Byte 2 The ASCII code for the key 'a'
Bytes 3-4 A keystroke mnemonic, '@E' (enter)
Other lengths of keyval are possible (maximum length 8 characters) as well as
other combinations of data.
ΓòÉΓòÉΓòÉ 3.18. Get_RexHLLAPI_Ver ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇver = RexHLLAPI('Get_RexHLLAPI_Ver')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the version of the REXHLAPI.DLL which is currently running. This
function does not execute any EHLLAPI services.
Prerequisite Calls:
None
Arguments:
None.
Returns:
The version and compilation date data string is returned.
'' Error, invalid number of arguments.
ver String containing REXHLAPI version info in the form 'x.xx mmm
[d]d,yyyy' where
o x.xx is the version number
o mmm is the month of compliation
o dd is the day of compilation (1 or 2 characters)
o yyyy is the year of compliation
Example:
version = substr(REXHLLAPI('Get_RexHLLAPI_Ver'), 1, 4)
compdate = substr(REXHLLAPI('Get_RexHLLAPI_Ver'), 6)
ΓòÉΓòÉΓòÉ 3.19. Pause (Service 18) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Pause', nΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Causes a timed pause of n 1/2 second intervals to occur.
If the Set_session_Parms service (described elsewhere) set IPAUSE and you have
done a Start_host_notify service, then the pause will also be ended by an
update to the to the host screen.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are 'Pause'.
n The number of 1/2 seconds to pause.
Returns:
The return code from the Pause EHLLAPI service is returned.
'0' Pause duration completed
'9' System error
'26' A host session has been updated, use Query_host_Update service for
more information
Example:
The following example
call REXHLLAPI 'Pause', 20
will cause a 10 second, or if IPAUSE has been set will cause a pause until the
host presentation space has been updated or 10 second pause whichever is
shorter.
ΓòÉΓòÉΓòÉ 3.20. PM_Window_Status (Service 104) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇstatusdata = RexHLLAPI('PM_Window_Status', statusdata)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Allows an application to query or change a PS window size, location, or visible
state.
Prerequisite Calls:
Connect_Window_Srvcs service
Arguments:
argument 1 The string constant or a variable whose contents are
'PM_Window_Status'.
statusdata 16 bytes of data specifying the status action to take. Refer to
the IBM Operating System/2 Extended Edition Version 1.2 EHLLAPI
Programming Reference manual for the layout of the data.
Returns:
The window status data string is returned.
'' Error. Check the value of the REXX variable HLLAPIRETC.
statusdata Function successful, status information returned
ΓòÉΓòÉΓòÉ 3.21. Post_Intercept_Status (Service 52) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Post_Intercept_Status', statusdataΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Informs EHLLAPI that a keystroke obtained through the Get_Key service was
accepted or rejected.
Prerequisite Calls:
Start_Key_Intercept service
Arguments:
argument 1 The string constant or a variable whose contents are
'Post_Intercept_Status'.
statusdata 2 bytes of data as follows:
o 1 byte indicating the session id or a blank specifying the current
connected session
o 1 byte option. 'A' for keystroke accepted or 'R' for keystroke rejected.
Returns:
The return code from the Post_Intercept_Status EHLLAPI service is returned.
'0' Ok
'1' Presentation space invalid
'2' Invalid option specified
'8' No prior Start_Keystroke_Intercept service has been called
'9' System error
Example:
The following example
keydata = REXHLLAPI('Get_key', 'A')
call REXHLLAPI 'Post_intercept_status', 'AR'
will reject the previous keystroke obtained by the Get_Key service.
ΓòÉΓòÉΓòÉ 3.22. Query_Close_Intercept (Service 42) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Query_Close_Intercept', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Allows the application to determine if the CLOSE option on the pull-down menu
was selected.
Prerequisite Calls:
Start_Close_Intercept service
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Close_Intercept'.
session_id The short session name of the presentation space to query
Returns:
The return code from the Query_Close_Intercept EHLLAPI service is returned.
'0' Close intercept did not occur
'1' Presentation space invalid
'2' Invalid parameter specified
'8' No prior Start_Close_Intercept service has been called
'9' System error
'12' The session is stopped
'26' A close intercept occurred since the last Query_Close_Intercept
service call
ΓòÉΓòÉΓòÉ 3.23. Query_Cursor_Loc (Service 7) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpos = RexHLLAPI('Query_Cursor_Loc')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the cursor position in the currently connected session or '0' if not
connected to a session.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Cursor_Loc'.
Returns:
The position of the cursor is returned.
'0' System error occured or not connected
> '0' The cursor position within the connected presentation space
ΓòÉΓòÉΓòÉ 3.24. Query_Field_Attr (Service 14) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇattr = RexHLLAPI('Query_Field_Attr', pos)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the text representation of the attribute of the field located at
position pos in the currently connected session or '0' if not connected to a
session or the session was currently an unformatted screen. The attribute bytes
are greater than x'C0' and are returned as printable characters ('C0' in this
case).
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Field_Attr'.
pos The position within the connected presentation space
Returns:
The field attribute byte is returned.
'' System error occured, not connected or the screen was unformatted.
Check the value of the REXX variable HLLAPIRETC.
attr One byte representation of the field attribute
ΓòÉΓòÉΓòÉ 3.25. Query_Host_Update (Service 24) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇretc = RexHLLAPI('Query_Host_Update', session_id)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Determines if the host has updated the presentation space, OIA or both since:
o The Start_Host_Notification service was called.
o A previous call to the Query_Host_Update service.
Prerequisite Calls:
Start_Host_Notify service
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Host_Update'.
session_id The short name for the presentation space to query
Returns:
The return code from the Query_Host_Update EHLLAPI service is returned.
'0' No update since last call
'1' Not connected to a session
'8' Host notification has not been requested (see the Start_Host_Notify
described elsewhere).
'9' System error
'21' The OIA has been updated
'22' The Presentation space has been updated
'23' Both OIA and PS have been updated
ΓòÉΓòÉΓòÉ 3.26. Query_Session_Status (Service 22) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇstatus = RexHLLAPI('Query_Session_Status', session_id)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns 18 bytes of session status information if the call is successful or ''
if not. The 18 bytes are layed out as follows:
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Session_Status'.
session_id The short name for the presentation space to query
Returns:
The session status data string is returned.
'' Error. Check the value of the REXX variable HLLAPIRETC.
status 18 bytes layed out as follows:
o 1 byte session short name
o 8 byte session long name in ASCII
o 1 byte session type
'D' DFT mode session
'C' CUT mode session
'F' 5250 session
o 1 byte binary number containing Control Program features
o 2 byte binary number (stored in normal Intel reversed format) containing
the number of rows in the session
o 2 byte binary number (stored in normal Intel reversed format) containing
the number of columns in the session
o 2 byte binary number (stored in normal Intel reversed format) containing
the host code page value.
Note: For the last three fields (row, col, codepage) use c2d(reverse(x))
after parsing them out of the string to get their decimal values
ΓòÉΓòÉΓòÉ 3.27. Query_sessions (Service 10) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇsessiondata = RexHLLAPI('Query_sessions')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns 12 bytes for each configured session or '' if an error occurred.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Sessions'.
Returns:
The session status data string is returned.
'' Error. Check the value of the REXX variable HLLAPIRETC.
sessiondata 12 bytes for each session layed out as follows:
o 1 byte session short name
o 8 byte session long name in ASCII
o 1 byte session type 'H'
o 2 byte binary number (stored in standard Intel reversed format)
containing the presentation space size for that session.
Note: For the last field (PSsize) use c2d(reverse(x)) after parsing it
out of the string to get the decimal value
Example:
The following example
session_info = REXHLLAPI('Query_sessions')
if length(session_info) < 13 then do
say 'No Comm. Mgr. sessions are active, canceling execution.'
exit
end
j = 1
session.0 = 0
do i = 13 by 12 for (length(session_info) / 12) - 1
if i > length(session_info) then leave
session.j = substr(session_info, i, 1)
j = j + 1
session.0 = session.0 + 1
end
will obtain all the short session id's and assign them to the stem variable
session with session.0 containing the total number of available sessions.
ΓòÉΓòÉΓòÉ 3.28. Query_system (Service 20) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇsysdata = RexHLLAPI('Query_system')ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns a 35 byte system configuration string or '' if an error occurred. The
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_System'.
Returns:
The system status data string is returned.
'' Error. Check the value of the REXX variable HLLAPIRETC.
sysdata 35 bytes layed out as follows:
o 1 byte EHLLAPI version (ASCII)
o 2 byte EHLLAPI level (ASCII)
o 6 bytes MMDDYY EHLLAPI date (ASCII)
o 3 bytes of not used data
o 1 byte hardware base, 'Z' means look at system bytes later, 'U' means
unable to determine, system bytes not valid
o 1 byte of 'X'
o 2 byte binary (stored in normal Intel reverse order) sequence number
o 2 bytes (ASCII) of the control program number
o 1 byte of '1'
o 4 byte ASCII Extended Error code 1
o 4 byte ASCII Extended Error code 2
o 2 byte binary (stored in normal Intel reverse order) of the hardware
base and sub-model types
x'FC00' 6 mhz AT
x'FC01' 8 mhz AT
x'FC02' XT 286
x'FC04' PS/2 Model 50
x'FC05' PS/2 Model 60
x'F800' PS/2 Model 80
x'F801' PS/2 Model 70
o 2 byte binary (stored in standard Intel reverse order) of the PC code
page being used
o 1 byte value identifying the display type being used
'C' CGA
'E' EGA
'V' VGA
'H' 8514
'A' 8503
'U' Unknown
o 3 bytes reserved and unused
ΓòÉΓòÉΓòÉ 3.29. Query_Window_Coords (Service 103) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇcoords = RexHLLAPI('Query_Window_Coords', session_id)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Returns the presentation space window coordinates.
Prerequisite Calls:
Connect_Window_Srvcs service
Arguments:
argument 1 The string constant or a variable whose contents are
'Query_Window_Coords'.
session_id The short name for the presentation space to query
Returns:
The window coordinates data string is returned.
'' Not connected to a session. Check the value of the REXX variable
HLLAPIRETC.
coords 17 bytes data containing the window coordinates data. Refer to the
IBM Operation System/2 Extended Edition Version 1.2 EHLLAPI
Programming Reference for more information on the layout of this
data.
ΓòÉΓòÉΓòÉ 3.30. Receive_File (Service 91) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Receive_File', stringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Executes the 'RECEIVE.EXE' program as if it had been entered at the command
line. The contents of string must be an acceptable syntax for the receive
command.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Receive_File'.
string Command line string per the syntax from the OS/2 Command
Reference
Returns:
Returns the return code from the RECEIVE program. Refer to the IBM Operating
System/2 Extended Edition Version 1.2 User's Guide Volume 2: Communications
Manager and LAN Requester manual for more information on the possible return
codes from this service.
Example:
ret = REXHLLAPI('Receive_File', 'c:\temp.pli temp.pli(xx) ascii crlf');
ΓòÉΓòÉΓòÉ 3.31. Release (Service 12) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Release'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Unlock the connected display session keyboard for user use.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are 'Release'.
Returns:
The return code from the Release EHLLAPI service is returned.
'0' Released
'1' Not connected
'9' System error occurred
Note: If you disconnect while the keyboard is locked (via Reserve service)
then a release will be done automatically.
ΓòÉΓòÉΓòÉ 3.32. Reserve (Service 11) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Reserve'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Locks the keyboard of the currently connected session until either a Release or
a Disconnect_PS is done.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are 'Reserve'.
Returns:
The return code from the Reserve EHLLAPI service is returned.
'0' Keyboard now locked
'1' Not connected to a session
'5' Not locked, session in input inhibit state
'9' System error
ΓòÉΓòÉΓòÉ 3.33. Reset_System (Service 21) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Reset_System'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Resets the system parameters (set with Set_session_parms service) to their
default state.
Note: Multiple processes may be using the same settings and ALL of them will
be reset by this call. Use it with care.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Reset_System'.
Returns:
The return code from the Reset_System EHLLAPI service is returned.
'0' Ok
'9' System error
ΓòÉΓòÉΓòÉ 3.34. Search_Field (Service 30) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpos = RexHLLAPI('Search_field', string, pos)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Search the currently connected session's presentation space for a field
containing the string string, starting at position pos.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Search_field'.
string The string to be search for.
pos The start position within the presentation space for the search
to begin.
Returns:
The position of the specified string is returned.
'0' String not found or error
> '0' Position within the presentation of the first location of string
ΓòÉΓòÉΓòÉ 3.35. Search_PS (Service 6) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇpos = RexHLLAPI('Search_PS', string, pos)ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Search the currently connect session's presentation space for the string string
starting at position pos. If SRCHALL has been specified in the
Set_Session_parms (described later), then pos is not used.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Search_PS'.
string The string to be search for.
pos The start position within the presentation space for the search
to begin.
Returns:
The position of the specified string is returned.
'0' String not found or error
> '0' Position within the presentation of the first location of string
ΓòÉΓòÉΓòÉ 3.36. Send_File (Service 90) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Send_File', stringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Executes the 'SEND.EXE' program as if it had been entered at the command line.
The contents of string must be an acceptable syntax for the send command.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Send_File'.
string Command line string per the syntax from the OS/2 Command
Reference.
Returns:
Returns the return code from the SEND program. Refer to the IBM Operating
System/2 Extended Edition Version 1.2 User's Guide Volume 2: Communications
Manager and LAN Requester manual for more information on the possible return
codes from this service.
Example:
ret = REXHLLAPI('Send_File', 'c:\temp.pli temp.pli(xx) ascii crlf');
ΓòÉΓòÉΓòÉ 3.37. Sendkey (Service 3) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Sendkey', stringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Send the keys as defined by the contents of string. Up to total of 255 keys may
be sent at a single time.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are 'Sendkey'.
string The string of characters to be sent to the currently connected
presentation space. This string can include the AID key
mnemonics. Some of the more common AID key mnemonics are:
'@E' Enter
'@C' Clear
'@n' PF1 through PF9 where n are the characters '1' through '9'. For a
complete list of all AID key mnemonics refer to the IBM Operating
System/2 Extended Edition Version 1.2 EHLLAPI Programming Reference
manual.
AID key mnemonics are case sensitive.
Returns:
The return code from the Sendkey EHLLAPI service is returned.
'0' Keystrokes sent
'1' Not connected to a session
'2' Incorrect parameter
'4' Session busy, all keystrokes not sent
'5' Session is in input inhibit state or invalid mnemonic sent
'9' System error occurred
Example:
The following example
call REXHLLAPI 'Sendkey', '@E'
will send the AID key Enter to the currently connected presentation space.
ΓòÉΓòÉΓòÉ 3.38. Set_Cursor (Service 40) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Set_Cursor', posΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Positions the cursor at position pos in the currently connected session.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are
'Set_Cursor'.
pos The position in the currently connected presentation space in
which to place the cursor.
Returns:
The return code from the Set_Cursor EHLLAPI service is returned.
'0' Ok
'1' Not connected to a session
'4' Session busy, all keystrokes not sent
'7' pos in invalid for the current presentation space
'9' System error occurred
ΓòÉΓòÉΓòÉ 3.39. Set_Session_Parms (Service 9) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Set_Session_parms', stringΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Sets the current session parameters from string.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Set_Session_parms'.
string The session parameter string. The values of the session
parameters are ASCII strings and are as follows:
'ATTRB' on read_PS calls, pass back ONLY the attributes of
the read string
'NOATTR'* pass back only the ASCII text in the read string
'EAB' pass back extended attributes AND text in the read
string
'NOEAB'* pass back only text in the read string
'XLATE' translate EABs to PC attribute values in the read
string
'NOXLATE'* do not translate EABs to PC attribute values in the
read string
'CONPHYS' connect to the physical session, and if required,
jump to it.
'CONLOG'* connect to the logical session requested, do not jump
to it
'ESC=n' set the keystroke mnemonic character to n, default
'@'
'SRCHALL'* Search the entire presentation space when doing
searches
'SRCHFROM' search ONLY from the specified position when doing
searches
'SRCHFRWD'* search from the beginning to the end of the PS
(forward direction)
'SRCHBKWD' search from the end of the PS to the beginning
(backward direction)
'AUTORESET'* will attempt to reset all inhibit conditions
automatically on sendkey requests
'NORESET' no reset will be attempted automatically
'TWAIT'* WAIT will wait up to one minute for XCLOCK or XSYSTEM
to clear before timing out
'LWAIT' WAIT will wait until XCLOCK or XSYSTEM clear before
returning
Note: This option should be used with EXTREME
caution as control will NOT return until the host is
available
'NWAIT' no wait, return status on any WAIT calls
'FPAUSE'* Full pause will take place regardless of any
Start_host_notify in effect.
'IPAUSE' Interruptible pause. If a pause is in progress, and a
host event occurs while Start_host_notify is in
effect, this pause will end.
Note: '*' denotes the default value for this
setting.
Please note that the session parameters STRLEN and
STREOT are not included in the list above. These
values cannot be changed through the REXHLAPI
function package.
More than one parameter may be set with a single
service call. Seperate multiple parameters with one
or more spaces.
Returns:
The return code from the Set_Session_parms EHLLAPI service is returned.
'0' Session parameters set
'2' Parameter string too long, or parameter error
'9' System error
Example:
The following example
call REXHLLAPI 'SetSession_Parms', 'NORESET IPAUSE'
will set the specified session parameters.
ΓòÉΓòÉΓòÉ 3.40. Start_Close_Intercept (Service 41) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Set_Close_Intercept', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Allows the application to intercept close requests when the user selects the
close option from the presentation space's window.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Start_Close_Intercept'.
session_id The short session name for the presentation space to begin
trapping close requests.
Returns:
The return code from the Start_Close_Intercept EHLLAPI service is returned.
'0' Ok
'1' Invalid session_id
'2' Parameter string error
'9' System error
'10' Function not supported
ΓòÉΓòÉΓòÉ 3.41. Start_Host_Notify (Service 23) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Start_Host_Notify', session_id, optionΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Starts trapping of host session screen update events. The session specified by
session_id will be monitored for changes as requested by option.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Start_Host_Notify'.
session_id The short session name for the presentation space to begin
trapping screen update events.
option Type of event trapping to begin. The valid values for option
are as follows:
'P' Screen changes only
'O' OIA changes only
'B' Both OIA and screen changes
Returns:
The return code from the Start_Host_Notify EHLLAPI service is returned.
'0' Ok
'1' Invalid session_id
'2' Parameter string error
'9' System error
ΓòÉΓòÉΓòÉ 3.42. Start_Key_Intercept (Service 50) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Start_Key_Intercept', session_id, optionΓöÇΓöÇΓöÇΓöÇ
Purpose:
All keystrokes to the session specified by session_id will be buffered for
processing by the Get_key service.
Prerequisite Calls:
None
Arguments:
argument 1 The string constant or a variable whose contents are
'Start_Key_Intercept'.
session_id The short session name for the presentation space to begin
trapping keystrokes.
option option can be either of the following
'D' AID keys only
'L' All keystroke
Returns:
The return code from the Start_Key_Intercept EHLLAPI service is returned.
'0' Ok, monitoring started
'1' Not connected to a session
'2' Option was not correct
'4' Session busy and cannot be connected
'9' System error
ΓòÉΓòÉΓòÉ 3.43. Stop_Close_Intercept (Service 43) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Stop_Close_Intercept', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Ends trapping of host session session_id close requests.
Prerequisite Calls:
Start_Close_Intercept service
Arguments:
argument 1 The string constant or a variable whose contents are
'Stop_Close_Intercept'.
session_id The short session name for the presentation space to stop
trapping close requests.
Returns:
The return code from the Stop_Close_Intercept EHLLAPI service is returned.
'0' Ok, monitoring ended
'1' Not connected to a session
'2' Parameter error
'8' No prior Start_Close_Intercept was done
'9' System error
'12' Session stopped
ΓòÉΓòÉΓòÉ 3.44. Stop_Host_Notify (Service 25) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Stop_Host_Notify', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Ends trapping of host session session_id screen update events started by a
preceding Start_Host_Notify service.
Prerequisite Calls:
Start_Host_Notify service
Arguments:
argument 1 The string constant or a variable whose contents are
'Stop_Host_Notify'.
session_id The short session name for the presentation space to stop
trapping screen and OIA updates.
Returns:
The return code from the Stop_Host_Notify EHLLAPI service is returned.
'0' Ok, monitoring ended
'1' Not connected to a session
'8' No prior Start_Host_Notify was done
'9' System error
ΓòÉΓòÉΓòÉ 3.45. Stop_Key_Intercept (Service 53) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Stop_Key_Intercept', session_idΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Ends trapping of keystrokes for session_id started by a preceding
Start_Keystroke_Interecpt service.
Prerequisite Calls:
Start_Key_Intercept service
Arguments:
argument 1 The string constant or a variable whose contents are
'Stop_Key_intercept'.
session_id The short session name for the presentation space to stop
trapping keystrokes.
Returns:
The return code from the Stop_Key_Intercept EHLLAPI service is returned.
'0' Ok, intercept ended
'1' Not connected to a session
'8' No prior Start_Keystroke_Intercept was done
'9' System error
ΓòÉΓòÉΓòÉ 3.46. Wait (Service 4) ΓòÉΓòÉΓòÉ
Syntax:
ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇCALL RexHLLAPI 'Wait'ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇ
Purpose:
Will check the status of the currently connected session. The setting (set by
the Set_session_parms service) of TWAIT, NWAIT ot LWAIT affects how long this
function will wait.
Prerequisite Calls:
Connect_PS service
Arguments:
argument 1 The string constant or a variable whose contents are 'Wait'.
Returns:
The return code from the Wait EHLLAPI service is returned.
'0' Keyboard unlocked and ready for keystrokes
'1' Not connected to a session
'4' Wait timed out while still in XCLOCK or XSYSTEM state
'5' Keyboard locked
'9' System error
ΓòÉΓòÉΓòÉ 4. Sample REXX Cmd using REXHLLAPI DLL Function Package ΓòÉΓòÉΓòÉ
The REXTEST3.CMD supplied on this distribution disk performs the following
functions:
o Requests session information from Communications Manager.
o Searches for an unused session.
o Logs on to TSO.
o Downloads a file to the c: drive.
o Logs off TSO.
Because all TSO/MVS/VTAM systems are different you may have to alter some of
the search strings for your particular system. Be sure to set the USERID and
PASSWORD variables to your TSO id and password.
ΓòÉΓòÉΓòÉ 5. Support of REXHLAPI DLL Function Package ΓòÉΓòÉΓòÉ
Support and enhancements for REXHLAPI will be performed by the author on an "as
time permits" basis. If you have questions, comments or suggestions on
improvements the author can be reached through the OS/2 Shareware BBS
(703-385-4325) or at the address below:
W. David Ashley
5 Timberline Dr.
Trophy Club, Tx 76262