SCOUG Logo


Next Meeting: Sat, Oct 19, 2019
Meeting Directions


Be a Member
Join SCOUG

Navigation:


Help with Searching

20 Most Recent Documents
Search Archives
Index by date, title, author, category.


Features:

Mr. Know-It-All
Ink
Download!




SCOUG:

Home

Email Lists

SIGs (Internet, General Interest, Programming, Network, more..)

Online Chats

Business

Past Presentations

Credits

Submissions

Contact SCOUG

Copyright SCOUG



warp expowest
Pictures from Sept. 1999


The views expressed in articles on this site are those of their authors.

warptech
SCOUG was there!


Copyright 2019, Southern California OS/2 User Group. ALL RIGHTS RESERVED.

SCOUG, Warp Expo West, and Warpfest are trademarks of the Southern California OS/2 User Group. OS/2, Workplace Shell, and IBM are registered trademarks of International Business Machines Corporation. All other trademarks remain the property of their respective owners.

The Southern California OS/2 User Group
P.O. Box 26904
Santa Ana, CA 92799-6904, USA
Using REXX and C Together - Part 1
Stan Shantar, Orange Hill Software and SCOUG Member
Introduction
Review of Part 1
Using C to Provide Enhanced Capabilities for REXX programs

Using C To Enhance REXX
Provide additional functions to REXX programs
Create Database, Communication, and Network interfaces
Provide PM GUI functionality
Provide advanced OS features (threads, semaphores, IPC)

Online Reference Materials
OS/2 Prodcedures Language 2/REXX (comes with Warp)
REXX Program Reference or Object REXX Programming Guide (comes with Developer's Toolkit and Visual Age C++)
Procedures Language 2/REXX User's Guide (REXXBASE.INF)

The Variable Pool Interface
REXX variables are stored as name-value string pairs
Variable Pool interface allows C program to set and fetch values
Fetch either by explicit name or enumeration
Multiple requests can be made in a single call to RexxVariablePool
Two types of name specification: Symbolic and Direct

The SHVBLOCK Structure
Used to create a linked list of requests
Definition: typedef struct _SHVBLOCK { struct _SHVBLOCK *shvnext; /* pointer to the next block */ RXSTRING shvname; /* name buffer */ RXSTRING shvvalue; /* value buffer */ ULONG shvnamelen; /* length of the name */ ULONG shvvaluelen; /* length of the value */ UCHAR shvcode; /* operation code */ UCHAR shvret; /* return code flags s*/ } SHVBLOCK; typedef SHVBLOCK *PSHVBLOCK;
Operation Codes and Return Flags
Operation codes:
RXSHV_SYSET
set
RXSHV_SYFETCH
fetch
RXSHV_SYDRO
drop
RXSHV_NEXTV
enumerate variables
RXSHV_PRIV
fetch private information
Return flags:
RXSHV_OK
RXSHV_NEWV
RXSHV_LVAR
RXSHV_TRUNC

The RexxVariablePool Function
Function prototype: APIRET APIENTRY RexxVariablePool(PSHVBLOCK);
Single argument - Pointer to 1st SHVBLOCK in list
Return code is aggregate of all return flags in list

The Subcommand Interface
Allows REXX program to use custom defined commands
Subcommand handler functions can be in either the executable or a DLL
Subcommand handler functions must be registered before use
Identified by "environment name" parameter in RexxStart
Many can be registered, but only one is effect

Subcommand Handler Functions
ALL subcommand handler functions MUST be defined as follows: ULONG EXPENTRY MySubcommandHandler( PRXSTRING prxCommand, /* cmd line */ PUSHORT pusFlags, /* ret flags */ PRXSTRING prxReturn ); /* ret string */
Register with RexxRegisterSubcomExe or RexxRegisterSubcomDll
Subcommand handler function must parse command line

External Functions
Extends the number of functions available to a REXX program
External functions can be in either the executable or a DLL
If packaged in a DLL, can form an API to another subsystem
REXX program does NOT have to started via RexxStart
External functions must be registered before use
No limit to number of functions that can be made available

External Function Definition
ALL external functions MUST be defined as follows: ULONG EXPENTRY MyExtFunction( PSZ pszName, /* function name */ ULONG ulArgv, /* arg count */ RXSTRING rxArgc, /* arg values */ PSZ pszQueueName, /* queue name */ PRXSTRING prxReturn ); /* ret value */
Register with RexxRegisterFunctionExe or RexxRegisterFunctionDll
If used in a DLL, use EXPORTS statements to provide case insensitivity
Note that arguments are parsed by the REXX interpreter

Creating An API For REXX Programs
Create a DLL containing a function to load the other functions: static PSZ pszRxFncTbl[] = { "OHSThis", "OHSThat", "OHSTheOtherThing"}; ULONG EXPENTRY LoadOHSFuncs (PSZ pszName, ULONG ulArgc, RXSTRING rxArgv[], PSZ pszQueue, PRXSTRING prxReturn); { LONG lEntries, i; prxReturn->strlength = 0; if (ulArgc > 0) return 40; /* s/b no args s/b passed */ lEntries = sizeof(pszRxFncTable)/sizeof(PSZ); for (i = 0; i<lEntries; i++) { RexxRegisterFunctionDll(pszRxFncTbl[i], "OHSDLL", pszRxFncTbl[i]); } return 0; }

Using the API in a REXX Program
First, add the loader function: /* rexx */ call RxFuncAdd "LoadOHSFuncs", "OHSDLL", "LoadOHSFuncs"
Then, invoke it: call LoadOHSFuncs Note the parallel to loading the REXXUTIL.DLL functions

Parameter Handling In External Functions
REXX always passes the value of a named variable used as an argument
To pass the NAME of a stem or return variable, enclose it in quotes
In the external function, use RexxVariablePool to fetch/set values
Stem variables and the "stem.0" convention

Halt and Trace Interface
RexxSetHalt raises a HALT condition in a running REXX program
RexxSetTrace turns on interactive debug mode
RexxResetTrace turns off interactive debug mode
Use in lieu of RXHLT and RXTRC exits
Multiple threads are implied - TID and PID must be known

Multiple Threads of REXX
Creating a multiple thread framework
External functions for transferring variable values across pools
External function wrappers for semaphores and other IPC facilities
Managing storage in the framework application